Skip to main content
POST
Create an activity

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a 409 idempotency_key_reused.

Maximum string length: 255

Body

application/json

Body for POST /v1/activities.

Send status: completed with a past due_at to log something that already happened rather than plan it.

due_at
string<date-time>
required

When it is planned for, or when it happened. May be past.

record_id
string
required

Id of a contact, organization or deal. The prefix names the kind of record.

Pattern: ^(con|org|deal)_[0-9a-f]{32}$
Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

title
string
required
Required string length: 1 - 500
assignee_id
string | null

Unique identifier for an user.

Pattern: ^usr_[0-9a-f]{32}$
Example:

"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

description
string
default:""
status
enum<string>
default:open
Available options:
open,
completed
type
enum<string>
default:task
Available options:
task,
call,
email,
meeting,
follow_up

Response

Successful Response

A call, meeting, task or other action planned or logged against a record.

created_at
string<date-time>
required
description
string
required
due_at
string<date-time>
required

When it is planned for, or when it happened. May be past.

id
string
required

Unique identifier for an activity.

Pattern: ^act_[0-9a-f]{32}$
Example:

"act_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

status
enum<string>
required

suggested is proposed but not yet accepted; conflict means it could not be carried out automatically — status_reason says why.

Available options:
open,
completed,
canceled,
conflict,
suggested
title
string
required
type
enum<string>
required

resume_conversation is the AI agent's plan to message the contact again at due_at; it can be read and canceled here, not created.

Available options:
task,
call,
email,
meeting,
follow_up,
resume_conversation
updated_at
string<date-time>
required
assignee
Owner · object | null

Who is responsible for doing it.

created_by
Owner · object | null

Who planned it. Null when an integration created it.

object
string
default:activity
Allowed value: "activity"
record_id
string | null

Id of a contact, organization or deal. The prefix names the kind of record.

Pattern: ^(con|org|deal)_[0-9a-f]{32}$
Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

status_reason
string | null

Why the activity was canceled or could not be carried out.