> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Activities

> Log notes, emails, calls and meetings on a contact's timeline, and read back every deal stage change.

**An activity is one thing that happened with a contact: a note, an email, a call, a meeting, or a deal moving stage.** Together they make the contact's timeline. Your team logs them in the dashboard, Crevio's agent logs them as it works, and you can log them through the API.

## The object

```json theme={null}
{
  "id": "act_9f2c1e4b7a6d5c3b2a1f0e9d",
  "object": "activity",
  "kind": "call",
  "body": "Wants the site visit before the end of the month. Prefers mornings.",
  "occurred_at": "2026-11-13T09:30:00Z",
  "ends_at": null,
  "contact": "con_abc123",
  "deal": "deal_abc123",
  "author_user": "user_abc123",
  "author_agent": null,
  "metadata": {},
  "created_at": "2026-11-13T09:41:12Z",
  "updated_at": "2026-11-13T09:41:12Z"
}
```

| Field | Meaning |
| - | - |
| `kind` | `note`, `email`, `call`, `meeting` or `stage`. |
| `body` | What was said or decided, up to 10,000 characters. Empty only on `stage`. |
| `occurred_at` | When it happened. Defaults to the moment you log it. The timeline is sorted by this. |
| `ends_at` | When a meeting ended. Only a `meeting` can have it. |
| `contact` | The contact it is about. Every kind except `meeting` needs one. |
| `deal` | The deal it belongs to, if any. A deal's activities always belong to the deal's contact. |
| `author_user` | The team member who logged it, when a person did. |
| `author_agent` | The chat (`aichat_...`) of the agent that logged it, when Crevio's agent did. |
| `metadata` | On `stage`, `from` and `to`: the stage keys the deal moved between. Empty on the other kinds. |

When neither `author_user` nor `author_agent` is set on a stage change, Crevio made the move, for example when a quote was accepted. On any other kind, it means the team member who logged it has since been removed from the account.

## Log an activity

```bash theme={null}
curl -X POST https://api.crevio.co/v1/activities \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "call",
    "contact": "con_abc123",
    "body": "Wants the site visit before the end of the month.",
    "occurred_at": "2026-11-13T09:30:00Z"
  }'
```

Pass `deal` instead of `contact` to put it on a deal; the deal's contact is filled in for you. Passing both with a contact that isn't the deal's answers `422`.

A `meeting` is the one kind that may have no contact, for a meeting you want on record before you know who it was with. It can also carry `ends_at`, which can't be earlier than `occurred_at`.

## Read the timeline

`GET /activities` lists activities newest first by `occurred_at`, and pages with `starting_after` like every other list.

| Parameter | Effect |
| - | - |
| `contact` | Only this contact's activities. |
| `deal` | Only this deal's activities. |
| `kind` | One kind or a comma-separated list, e.g. `call,meeting`. An unknown kind answers `400`. |
| `from` | Only activities that occurred at or after this ISO 8601 time. |
| `to` | Only activities that occurred before this ISO 8601 time. |

```bash theme={null}
curl "https://api.crevio.co/v1/activities?deal=deal_abc123&kind=stage" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

The contact's page in the dashboard also shows their orders, bookings, form submissions and tags on the same timeline. Those are not activities: read them from `/orders`, `/bookings` and `/form_submissions`.

## Stage changes

Every time a deal moves, Crevio writes a `stage` activity with `metadata.from` and `metadata.to`. That happens however the deal moved: dragged on the board, `POST /deals/{id}/move`, a sent or accepted quote, or a removed stage.

Stage changes are the record of what happened, so they can't be logged, edited or deleted by hand. `POST /activities` with `kind: "stage"` answers `400`. `PATCH` or `DELETE` on one answers `409` with code `activity_immutable`. Deleting the deal deletes its stage changes; its other activities stay on the contact's timeline.

## Change or delete an activity

`PATCH /activities/{id}` changes `kind`, `body`, `occurred_at`, `ends_at`, `contact` or `deal`. Send `""` for `contact` or `deal` to clear it; only a meeting can be left without a contact. A timestamp that isn't ISO 8601 answers `400` with code `parameter_invalid`. `DELETE /activities/{id}` removes it. When Crevio's agent deletes one, it asks you first.

## Webhooks

`activity.created` fires when a note, email, call or meeting is logged, `activity.updated` when one is edited, and `activity.deleted` when one is deleted. Each carries the activity with the contact and deal expanded. Stage changes send none of them: listen for `deal.stage_changed` instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.