Activities

Activities are the timeline of CRM events on a contact or company — notes you took, calls you had, meetings you scheduled, tasks you owe, and reminders you set. The API exposes a read endpoint for a contact’s activity timeline and a write endpoint to log new activities.

The Activity object

string

string | null

The contact this activity is logged against. Either contact_id or company_id is set.

string | null

The company this activity is logged against. Either contact_id or company_id is set.

string

One of note, call, meeting, video_call, task, todo, reminder.

string | null

ISO 8601 timestamp. Used for task, todo, and reminder activities.

number | null

Duration in minutes. Useful for call, meeting, and video_call.

string | null

ISO 8601 timestamp marking the activity as done.

object

Free-form JSON for extra context (call recording URL, meeting attendees, etc.).

string

ISO 8601 timestamp.

Activity types

Type	Use for
`note`	Free-form notes recorded against a contact or company
`call`	Phone calls made or received
`meeting`	In-person or scheduled meetings
`video_call`	Zoom, Google Meet, etc.
`task`	Work to be done, typically with a `due_date`
`todo`	Lightweight checklist items
`reminder`	Time-based prompts to follow up

For more on how Clarky’s CRM uses activities, see the CRM Activity feature docs.

List a contact’s activities

GET

GET /api/v1/contacts/{contact_id}/activities

Returns a paginated, reverse-chronological timeline of activities on a single contact.

Query parameters

Param	Type	Description
`activity_type`	string	Filter to a single activity type (e.g. `note`, `call`)
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/contacts/c_01HXYZ/activities?activity_type=call" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "a_01HACT...",
      "contact_id": "c_01HXYZ...",
      "company_id": null,
      "activity_type": "call",
      "title": "Discovery call",
      "description": "Walked through the platform, customer is interested in the Pro plan.",
      "due_date": null,
      "duration_minutes": 32,
      "completed_at": "2026-04-29T15:30:00.000Z",
      "metadata": { "outcome": "qualified" },
      "created_at": "2026-04-29T15:31:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}

Log an activity

POST

POST /api/v1/activities

Requires a key with the write scope. Each activity must be linked to either a contact_id or a company_id (you can pass both, but at least one is required).

Body fields

Field	Type	Required	Description
`activity_type`	string	Yes	One of `note`, `call`, `meeting`, `video_call`, `task`, `todo`, `reminder`
`contact_id`	string	Conditional	Required unless `company_id` is provided
`company_id`	string	Conditional	Required unless `contact_id` is provided
`title`	string	No
`description`	string	No
`due_date`	string (ISO 8601)	No	Useful for `task`, `todo`, `reminder`
`duration_minutes`	number	No	Useful for `call`, `meeting`, `video_call`
`completed_at`	string (ISO 8601)	No	Mark the activity as already done
`metadata`	object	No	Free-form JSON

Example: log a note

curl https://clarky.ai/api/v1/activities \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "note",
    "contact_id": "c_01HXYZ",
    "title": "Follow-up needed",
    "description": "Customer asked about migration help next quarter."
  }'

{
  "data": {
    "id": "a_01HACT...",
    "contact_id": "c_01HXYZ...",
    "company_id": null,
    "activity_type": "note",
    "title": "Follow-up needed",
    "description": "Customer asked about migration help next quarter.",
    "due_date": null,
    "duration_minutes": null,
    "completed_at": null,
    "metadata": {},
    "created_at": "2026-04-29T19:25:00.000Z"
  }
}

Example: schedule a task

curl https://clarky.ai/api/v1/activities \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "task",
    "contact_id": "c_01HXYZ",
    "title": "Send follow-up proposal",
    "due_date": "2026-05-06T17:00:00.000Z"
  }'

{
  "data": {
    "id": "a_01HACT...",
    "contact_id": "c_01HXYZ...",
    "activity_type": "task",
    "title": "Send follow-up proposal",
    "due_date": "2026-05-06T17:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-04-29T19:26:00.000Z"
  }
}

Getting Started

Resources

The Activity object

Activity types

List a contact’s activities

Query parameters

Example

Log an activity

Body fields

Example: log a note

Example: schedule a task

​The Activity object

​Activity types

​List a contact’s activities

​Query parameters

​Example

​Log an activity

​Body fields

​Example: log a note

​Example: schedule a task

The Activity object

Activity types

List a contact’s activities

Query parameters

Example

Log an activity

Body fields

Example: log a note

Example: schedule a task