Skip to main content
POST
Create a Helpdesk ticket
Authenticate with a Full access workspace API key, or as an active Owner, Member, or Support Associate in the workspace that owns the agent. A read-only key or a Viewer receives 403 FORBIDDEN. See authentication and workspace roles.

Authorizations

Authorization
string
header
required

A Clerk bearer token associated with the active workspace. Browser sessions may use their authenticated session cookie.

Headers

Idempotency-Key
string
required

A caller-generated key, unique to this logical ticket creation. Replays must send the same request body.

Required string length: 1 - 128

Path Parameters

agentId
string
required

Agent ID in the authenticated workspace.

Required string length: 1 - 128

Body

application/json
subject
string
required
Required string length: 1 - 500
description
string
required
Required string length: 1 - 10000
customer
object
required
statusId
string

An active status belonging to this agent. Do not combine with statusCategory.

statusCategory
enum<string>

Uses the agent's default status for this category. Defaults to new. Do not combine with statusId.

Available options:
new,
on_you,
on_customer,
on_hold,
closed,
cancelled
assigneeId
string | null

An active Helpdesk member ID, or null to suppress automatic assignment. Do not combine with assigneeEmail.

assigneeEmail
string<email>

An active Helpdesk member email. Do not combine with assigneeId.

teamId
string

A team belonging to this agent. The default team is used when omitted.

customFields
object

Up to 50 active custom fields keyed by field ID. Dropdown values use option IDs. Dates use YYYY-MM-DD.

Response

The new or idempotently replayed ticket.

ticketNumber
integer
required
subject
string
required
description
string
required
statusCategory
enum<string>
required
Available options:
new,
on_you,
on_customer,
on_hold,
closed,
cancelled
statusId
string
required
assigneeId
string | null
required
customer
object
required
customFields
object
required
channel
enum<string>
required
Available options:
api
teamId
string | null
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
lastMessageAt
string<date-time> | null
required
Last modified on October 14, 2026