Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
id
string
​
contact_id
string | null
The contact this activity is logged against. Either contact_id or company_id is set.
​
company_id
string | null
The company this activity is logged against. Either contact_id or company_id is set.
​
activity_type
string
One of note, call, meeting, video_call, task, todo, reminder.
​
title
string | null
​
description
string | null
​
due_date
string | null
ISO 8601 timestamp. Used for task, todo, and reminder activities.
​
duration_minutes
number | null
Duration in minutes. Useful for call, meeting, and video_call.
​
completed_at
string | null
ISO 8601 timestamp marking the activity as done.
​
metadata
object
Free-form JSON for extra context (call recording URL, meeting attendees, etc.).
​
created_at
string
ISO 8601 timestamp.

​
Activity types

TypeUse for
noteFree-form notes recorded against a contact or company
callPhone calls made or received
meetingIn-person or scheduled meetings
video_callZoom, Google Meet, etc.
taskWork to be done, typically with a due_date
todoLightweight checklist items
reminderTime-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

​
method
GET
GET /api/v1/contacts/{contact_id}/activities
Returns a paginated, reverse-chronological timeline of activities on a single contact.

​
Query parameters

ParamTypeDescription
activity_typestringFilter to a single activity type (e.g. note, call)
pageintegerSee Pagination
page_sizeintegerSee 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

​
method
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

FieldTypeRequiredDescription
activity_typestringYesOne of note, call, meeting, video_call, task, todo, reminder
contact_idstringConditionalRequired unless company_id is provided
company_idstringConditionalRequired unless contact_id is provided
titlestringNo
descriptionstringNo
due_datestring (ISO 8601)NoUseful for task, todo, reminder
duration_minutesnumberNoUseful for call, meeting, video_call
completed_atstring (ISO 8601)NoMark the activity as already done
metadataobjectNoFree-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"
  }
}