Activities

Activities represent interactions with contacts — phone calls, emails, and meetings. Each activity type has its own metadata schema.

The Activity Object

Field	Type	Description
id	uuid	Unique identifier
account_id	uuid	Account this activity belongs to
created_by	uuid | null	User who created the activity
activity_type	string	Type: call, email, meeting
contact_id	uuid | null	Associated contact
company_id	uuid | null	Associated company
project_id	uuid | null	Associated project
occurred_at	datetime	When the activity happened
metadata	object	Type-specific fields (see below)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
created_by_name	string	Creator name (read-only, computed)
contact_name	string	Contact name (read-only, computed)
company_name	string	Company name (read-only, computed)
project_name	string	Project name (read-only, computed)

Activity Types and Metadata

Call

Field	Type	Options	Description
direction	enum	inbound, outbound	Call direction
outcome	enum	connected, voicemail, no_answer, busy	Call result
duration_seconds	integer	–	Call duration
notes	string	–	Call notes

Email

Field	Type	Options	Description
direction	enum	sent, received	Email direction
subject	string	–	Email subject line
body	string	–	Email body text
source	enum	manual, bcc	How the email was logged

Meeting

Field	Type	Options	Description
subject	string	–	Meeting subject
location	string	–	Meeting location
duration_minutes	integer	–	Duration in minutes
outcome	enum	completed, cancelled, no_show	Meeting result
notes	string	–	Meeting notes

List Activities

Endpoint: activities-list

Field	Type	Required	Description
contact_id	uuid	No	Filter by contact
company_id	uuid	No	Filter by company
project_id	uuid	No	Filter by project
types	string[]	No	Filter by activity types
cursor	string	No	Pagination cursor
limit	integer	No	Results per page

curl -X POST https://api.driftwoodapp.com/api/activities-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "types": ["call", "meeting"],
    "limit": 20
  }'

Response:

{
  "ok": true,
  "result": {
    "items": [
      {
        "id": "770e8400-...",
        "activity_type": "call",
        "contact_id": "550e8400-...",
        "contact_name": "Jane Smith",
        "occurred_at": "2025-06-15T14:30:00Z",
        "metadata": {
          "direction": "outbound",
          "outcome": "connected",
          "duration_seconds": 420,
          "notes": "Discussed Q3 proposal"
        },
        "created_by_name": "Alex Johnson",
        "created_at": "2025-06-15T14:35:00Z"
      }
    ],
    "next_cursor": ""
  }
}

Get Activity

Endpoint: activities-get

Field	Type	Required	Description
id	uuid	Yes	Activity ID

Create Activity

Endpoint: activities-create

Field	Type	Required	Description
activity_type	string	Yes	call, email, or meeting
contact_id	uuid	No*	Associated contact
company_id	uuid	No*	Associated company
project_id	uuid	No*	Associated project
occurred_at	datetime	No	When it happened (defaults to now)
metadata	object	No	Type-specific fields

*At least one of contact_id, company_id, or project_id is required.

curl -X POST https://api.driftwoodapp.com/api/activities-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "call",
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "occurred_at": "2025-06-15T14:30:00Z",
    "metadata": {
      "direction": "outbound",
      "outcome": "connected",
      "duration_seconds": 420,
      "notes": "Discussed Q3 proposal"
    }
  }'

Update Activity

Endpoint: activities-update

Field	Type	Required	Description
id	uuid	Yes	Activity ID
occurred_at	datetime	No	Update timestamp
metadata	object	No	Update metadata fields

Delete Activity

Endpoint: activities-delete

Field	Type	Required	Description
id	uuid	Yes	Activity ID

Activity Schemas

Retrieve the metadata schema for each activity type. Useful for building dynamic forms.

Endpoint: activity-schemas-list

curl -X POST https://api.driftwoodapp.com/api/activity-schemas-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "ok": true,
  "result": {
    "schemas": [
      {
        "type": "call",
        "label": "Call",
        "fields": [
          {
            "name": "direction",
            "type": "enum",
            "label": "Direction",
            "required": false,
            "options": ["inbound", "outbound"]
          },
          {
            "name": "outcome",
            "type": "enum",
            "label": "Outcome",
            "required": false,
            "options": ["connected", "voicemail", "no_answer", "busy"]
          },
          {
            "name": "duration_seconds",
            "type": "integer",
            "label": "Duration (seconds)",
            "required": false
          },
          {
            "name": "notes",
            "type": "string",
            "label": "Notes",
            "required": false
          }
        ]
      }
    ]
  }
}

Error Codes

Code	Description
activities.invalid_request	Malformed request body
activities.invalid_id	Invalid UUID format
activities.invalid_type	Type must be: call, email, meeting
activities.entity_required	Must provide contact_id, company_id, or project_id
activities.invalid_metadata	Metadata doesn’t match schema for the activity type
activities.not_found	Activity does not exist
activities.internal	Server error