Skip to main content
POST
Create a task

Authorizations

Authorization
string
header
required

OAuth 2.0 Bearer Token from Clerk authentication

Headers

Idempotency-Key
string

Unique key to ensure idempotent request handling. If a request with the same key was already processed, the original response will be returned.

Body

application/json
book_id
string
required

The book ID

Example:

"abc123xyz"

title
string
required

Task title

Example:

"Follow up with client"

description
string

Task description

Example:

"Call to discuss portfolio"

deadline_at
string<date-time>

Deadline for the task

Example:

"2024-12-31T23:59:59Z"

all_day
boolean
default:true

Whether this is an all-day task

status
enum<string>
default:todo

Task status

Available options:
todo,
done
priority
enum<string>

Task priority

Available options:
low_priority,
medium_priority,
high_priority,
urgent_priority
is_private
boolean
default:false

When true, only the creator, assignee (or members of the assigned team), and collaborators can see this task. Defaults to false.

household_id
string

Associate task with a household (mutually exclusive with contact_id and business_id)

contact_id
string

Associate task with a contact (mutually exclusive with household_id and business_id)

business_id
string

Associate task with a business (mutually exclusive with household_id and contact_id)

assigned_to_id
string

User ID from the relevant book users list to assign the task to

assigned_team_id
string

Team ID to assign the task to (mutually exclusive with assigned_to_id)

tag_ids
string[]

Label IDs to apply to the task

Response

task created

id
string
required

The task ID

Example:

"abc123xyz"

title
string
required

Task title

Example:

"Follow up with client"

all_day
boolean
required

Whether this is an all-day task

status
enum<string>
required

Task status

Available options:
todo,
done
created_at
string<date-time>
required

When the task was created

updated_at
string<date-time>
required

When the task was last updated

description
string | null

Task description

deadline_at
string<date-time> | null

Deadline for the task

priority
enum<string> | null

Task priority

Available options:
low_priority,
medium_priority,
high_priority,
urgent_priority
is_private
boolean

When true, only the creator, assignee (or members of the assigned team), and collaborators can see this task. Use for sensitive tasks like HR or payroll.

completed_at
string<date-time> | null

When the task was completed

assigned_to
object | null
assigned_team
object | null
record
object | null

The associated record (household, contact, or business) this task is linked to

tags
object[]

Labels applied to the task