Skip to main content
POST
Create a ticket
Replace {your-subdomain} with your workspace’s subdomain.
Learn how to find your subdomain in Workspace subdomain.

Headers

X-Api-Key
string
default:your-api-key
required

Use the X-Api-Key header to provide your workspace API key. Refer to Authentication for more information.

Body

application/json
email
string
required

Email address of the customer.

Example:

"john@example.com"

subject
string
required

Subject for the ticket.

Example:

"How to resolve the pending payments"

description
string
required

Description for the ticket.

Example:

"I need your help in resolving the pending payments."

ticket_fields
object

Custom ticket fields. Refer to the ticket fields article for more details.

Example:
name
string

Name of the customer.

Example:

"John Luther"

channel
enum<string>

Source of the ticket. Defaults to api if not specified or if an invalid channel is provided.

Available options:
email,
ui,
twitter,
chat,
form,
api,
whatsapp,
telephony
Example:

"email"

to
string

Array of additional emails to be added to the to field of any responses from the ticket.

Example:

"[\"eve@example.com\",\"kevin@example.com\"]"

cc
string

Array of emails to be added to the cc field of any responses from the ticket.

Example:

"[\"eve@example.com\",\"kevin@example.com\"]"

group
string

Name of an existing group.

Example:

"sales"

assignee_email
string<email>

Email address belonging to a team member.

Example:

"oliver@example.com"

status
string

Status for the ticket. Default statuses are new, open, on_hold, waiting_on_customer, closed, spam and trash. Custom statuses are also supported. There is no resolved status, so a source ticket that was resolved maps to closed, paired with closed_at. trash cannot be set at creation.

Example:

"open"

priority
enum<string>

Priority for the ticket.

Available options:
low,
medium,
high,
urgent
Example:

"low"

category
string

Category for the ticket. Default categories include None, Questions, Incident, Problem, Feature request, Refund. Custom categories are also supported.

Example:

"Questions"

sub_category_one
string

Sub-category for the ticket.

Example:

"Billing"

sub_category_two
string

Second-level sub-category for the ticket.

Example:

"Refund"

tags
string[]

Tags to assign to the ticket.

Example:
created_at
string<date-time>

Original creation time, for importing a historical ticket. ISO 8601. Supplying any of created_at, updated_at or closed_at marks the request as an import. A value that cannot be parsed is rejected rather than quietly stored as the time of the request.

Example:

"2021-03-04T10:00:00Z"

updated_at
string<date-time>

Original time of last activity. ISO 8601. Comments added afterwards with their own created_at carry this forward to the latest comment's date, and never move it backwards.

Example:

"2021-06-09T12:00:00Z"

closed_at
string<date-time>

Original close time, used together with status: closed. ISO 8601. It also sets the resolution timestamp and the resolution time that agent and team performance reports average. Omit it on a ticket created closed and the ticket's own created_at is recorded, giving a zero resolution time rather than inventing the whole gap up to today.

Example:

"2021-03-07T10:00:00Z"

skip_notifications
boolean

Suppresses everything creating a ticket would otherwise set off: automation rules and any email they send, webhooks, agent push notifications, Zapier, Google Sheets, product analytics, the timeline entry, and SLA escalation for a due date that has already passed. Defaults to true when any of created_at, updated_at or closed_at is supplied, because backdating implies an import. Send false to backdate and still notify.

Because webhooks and Zapier are among the things it suppresses, anything downstream that mirrors your tickets will not see the imported ones and has to be reconciled separately.

Example:

true

external_id
string

Identifier for this ticket in the system it came from. Stored, returned on the ticket, and filterable through GET /tickets?external_id=, so a repeated import can find what it already created instead of duplicating it.

Example:

"CP-1234"

source
string

Name of the system external_id refers to. Only meaningful alongside external_id.

Example:

"concierge_plus"

attachments
string[]

Signed ids returned by Upload attachment. The files are attached to the ticket's opening message. A signed id minted in another workspace is rejected. Attachments are all-or-nothing: if any id in the array is unknown, malformed or from another workspace, the whole request fails and no ticket is created.

Example:

Response

201 - application/json

Created - Ticket created successfully

ticket
object