> ## 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

> Log notes, calls, meetings, tasks, and reminders against contacts and companies

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

<ResponseField name="id" type="string" />

<ResponseField name="contact_id" type="string | null">
  The contact this activity is logged against. Either `contact_id` or `company_id` is set.
</ResponseField>

<ResponseField name="company_id" type="string | null">
  The company this activity is logged against. Either `contact_id` or `company_id` is set.
</ResponseField>

<ResponseField name="activity_type" type="string">
  One of `note`, `call`, `meeting`, `video_call`, `task`, `todo`, `reminder`.
</ResponseField>

<ResponseField name="title" type="string | null" />

<ResponseField name="description" type="string | null" />

<ResponseField name="due_date" type="string | null">
  ISO 8601 timestamp. Used for `task`, `todo`, and `reminder` activities.
</ResponseField>

<ResponseField name="duration_minutes" type="number | null">
  Duration in minutes. Useful for `call`, `meeting`, and `video_call`.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  ISO 8601 timestamp marking the activity as done.
</ResponseField>

<ResponseField name="metadata" type="object">
  Free-form JSON for extra context (call recording URL, meeting attendees, etc.).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

## 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                       |

<Tip>
  For more on how Clarky's CRM uses activities, see the [CRM Activity feature docs](/features/crm/activity).
</Tip>

***

## List a contact's activities

<ParamField path="method" type="GET">
  `GET /api/v1/contacts/{contact_id}/activities`
</ParamField>

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](/api-reference/pagination)            |
| `page_size`     | integer | See [Pagination](/api-reference/pagination)            |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts/c_01HXYZ/activities?activity_type=call" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "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

<ParamField path="method" type="POST">
  `POST /api/v1/activities`
</ParamField>

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

```bash theme={null}
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."
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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"
  }
}
```