Getting started with tickets

A ticket is a support case you open on a customer conversation (a thread). It records what the problem is, who is working on it and where it stands. This section lets you create tickets, read them, change them, and look up the agents and statuses you can use.

What you want to do	Endpoint
See the tickets of a conversation	`GET /thread-ticket/get-tickets`
Open a ticket	`POST /thread-ticket/create-ticket`
Change a ticket (details, agents, status)	`PUT /thread-ticket/update-ticket`
List the ticket statuses you can use	`GET /thread-ticket/get-status-list`
List the agents you can assign	`GET /ticket/agents`

There is no endpoint to delete a ticket.

1. The big picture

Conversation (thread)
 └─ Ticket  (reference number such as 100001)
      ├─ Details   one value per ticket field (for example Subject)
      ├─ Agents    the people working on it
      └─ Statuses  one main status + optional sub-statuses

A conversation can have several tickets.

A ticket only works with conversations of your own organization.

2. Before you create a ticket: what you need

What you need	Where to find it
`thread_id` of the conversation	Get Inbox Data (`GET /thread/inbox`)
Ticket field IDs (the "details" you can fill in)	Get Ticket Fields (`GET /global/thread-ticket-field`) `[CONFIRM BEFORE PUBLISHING: this lookup is not public yet]`
Ticket status IDs	Get Ticket Statuses (`GET /thread-ticket/get-status-list`)
Agent IDs (optional)	Get Agents (`GET /ticket/agents`)

INFO

Ticket statuses are not thread statuses. The status you set on a conversation in the Inbox (Assign Thread Status) comes from a different list (Get Thread Status Types). A ticket has its own statuses, from Get Ticket Statuses. Do not mix the IDs.

3. Ticket fields (the details)

Each ticket stores its details as fields. Fields are the same for everyone. Get Ticket Fields lists them:

{
  "status": true,
  "data": [
    {
      "thread_ticket_field_id": "12121212-1212-1212-1212-121212121212",
      "thread_ticket_field_name": "Subject",
      "data_type_name": "Text",
      "flag_required": true,
      "flag_allowed_multiple": false
    }
  ]
}

Field	What it means
`flag_required`	`true`: you must send a non-empty value for it every time you create or update a ticket.
`flag_allowed_multiple`	`false`: you can send only one value for it. `true`: you can send several.

The names and values above are samples. Always read the real list.

4. Statuses: one main status, and sub-statuses

Get Ticket Statuses returns the built-in statuses plus any your organization added.

{
  "status": true,
  "data": [
    {
      "ticket_status_id": "15151515-1515-1515-1515-151515151515",
      "ticket_status_name": "Open",
      "flag_substatus": false,
      "ticket_status_color": "#00AA00",
      "organization_id": null,
      "created_timestamp": "2026-01-01T00:00:00.000Z",
      "updated_timestamp": "2026-01-01T00:00:00.000Z"
    },
    {
      "ticket_status_id": "16161616-1616-1616-1616-161616161616",
      "ticket_status_name": "Waiting on customer",
      "flag_substatus": true,
      "ticket_status_color": "#FFAA00",
      "organization_id": 1,
      "created_timestamp": "2026-01-01T00:00:00.000Z",
      "updated_timestamp": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The names above are samples.

Field	What it means
`flag_substatus`	`false` = a main status. `true` = a sub-status (extra detail on top of a main status).
`organization_id`	`null` = built into Chronox. A number = created by your organization.

The rule: when you give a ticket statuses, it must have exactly one main status. You can add any number of sub-statuses next to it, but never the same status twice.

5. Agents

Get Agents lists the people in your organization you can assign to a ticket.

{
  "status": true,
  "data": [
    {
      "organization_id": 1,
      "user_assignment_id": 1001,
      "private_user_id": 301,
      "private_user_email": "agent@example.com",
      "private_user_first_name": "Agent",
      "private_user_last_name": "Smith"
    }
  ]
}

Use user_assignment_id as agent_user_assignment_id when you create or update a ticket. Agents must belong to your organization.

6. Create a ticket

POST /thread-ticket/create-ticket

{
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "field_data": [
    { "thread_ticket_field_id": "12121212-1212-1212-1212-121212121212", "field_value": "Refund not received" }
  ],
  "agent_assignments": [
    { "agent_user_assignment_id": 1001 }
  ],
  "status_assignments": [
    { "ticket_status_id": "15151515-1515-1515-1515-151515151515" }
  ]
}

Field	Required	Notes
`thread_id`	Yes	A conversation of your organization.
`field_data`	Yes, in practice	Every field marked required must have a non-empty value.
`agent_assignments`	No	Leave it out or send `[]` for an unassigned ticket.
`status_assignments`	Yes	At least one, with exactly one main status (section 4).

You get the new ticket back:

{
  "status": true,
  "data": {
    "thread_ticket_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organization_id": 1,
    "created_by_user_assignment_id": 1001,
    "ticket_reference_number": "100001",
    "created_timestamp": "2026-01-01T00:00:00.000Z",
    "updated_timestamp": "2026-01-01T00:00:00.000Z",
    "field_data": [
      {
        "thread_ticket_field_data_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "thread_ticket_field_id": "12121212-1212-1212-1212-121212121212",
        "thread_ticket_field_name": "Subject",
        "field_value": "Refund not received",
        "created_timestamp": "2026-01-01T00:00:00.000Z"
      }
    ],
    "agent_assignments": [
      {
        "thread_ticket_agent_assignment_id": "13131313-1313-1313-1313-131313131313",
        "agent_user_assignment_id": 1001,
        "user_id": 301,
        "agent_name": "Agent Smith",
        "agent_first_name": "Agent",
        "agent_last_name": "Smith",
        "agent_email": "agent@example.com",
        "timestamp_assigned": "2026-01-01T00:00:00.000Z",
        "timestamp_left": null
      }
    ],
    "status_assignments": [
      {
        "thread_ticket_status_assignment_id": "14141414-1414-1414-1414-141414141414",
        "ticket_status_id": "15151515-1515-1515-1515-151515151515",
        "ticket_status_name": "Open",
        "flag_substatus": false,
        "ticket_status_color": "#00AA00",
        "created_timestamp": "2026-01-01T00:00:00.000Z",
        "updated_timestamp": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}

Save the thread_ticket_id, and the three kinds of row IDs inside it (thread_ticket_field_data_id, thread_ticket_agent_assignment_id, thread_ticket_status_assignment_id). You need them to update the ticket.

The reference number. ticket_reference_number is a 6-digit text value, starting at 100000. Numbers are shared across all Chronox customers, so yours will not be consecutive. Quote it when you talk to your customer or to support.

Agents you assign are notified.

7. See tickets

GET /thread-ticket/get-tickets?thread_id=3fa85f64-5717-4562-b3fc-2c963f66afa6

thread_id is required. You get all tickets of that conversation, newest first, each in the same shape as section 6. A conversation with no tickets returns "data": [].

You can only read tickets of your own organization's conversations. There is no way to list all tickets of your organization in one call; go through the conversations you care about.

8. Change a ticket

PUT /thread-ticket/update-ticket

WARNING

Update means "this is the full picture". Anything you leave out of the three lists (field_data, agent_assignments, status_assignments) is removed from the ticket. Always read the ticket first with Get Tickets, change what you need and send everything back.

{
  "thread_ticket_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
  "field_data": [
    {
      "thread_ticket_field_data_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "thread_ticket_field_id": "12121212-1212-1212-1212-121212121212",
      "field_value": "Refund issued"
    }
  ],
  "agent_assignments": [
    {
      "thread_ticket_agent_assignment_id": "13131313-1313-1313-1313-131313131313",
      "agent_user_assignment_id": 1002
    }
  ],
  "status_assignments": [
    {
      "thread_ticket_status_assignment_id": "14141414-1414-1414-1414-141414141414",
      "ticket_status_id": "16161616-1616-1616-1616-161616161616"
    }
  ]
}

How each list works:

List	Row with its row ID	Row without a row ID	Row missing from your list
`field_data` (`thread_ticket_field_data_id`)	Value is updated if it changed.	A new value is added.	Removed.
`agent_assignments` (`thread_ticket_agent_assignment_id`)	The agent is replaced if you send a different `agent_user_assignment_id`.	A new agent is assigned.	The agent is unassigned.
`status_assignments` (`thread_ticket_status_assignment_id`)	The status is replaced if you send a different `ticket_status_id`.	A new status is added.	Removed.

Other rules:

Row IDs must belong to this ticket, otherwise you get error 9001.

Every field_data row needs its thread_ticket_field_id, even when you only change the value.

Required fields must still be present with a non-empty value, even if they did not change.

If you send any statuses, there must be exactly one main status in the list. Sending "status_assignments": [] removes all statuses.

Agents you add (or swap in) get an "assigned" notification. Agents you remove (or swap out) get an "unassigned" notification.

You get the updated ticket back, in the same shape as section 6.

Common changes

I want to...	Send
Close or move the ticket	The same `status_assignments` row (with its ID) and the new main `ticket_status_id`. Keep the rest of the lists as they were.
Hand it to another agent	The same `agent_assignments` row (with its ID) and the new `agent_user_assignment_id`.
Add a second agent	Keep the existing row and add one more row without an ID.
Remove all agents	`"agent_assignments": []`.

9. Common errors

Errors come back with HTTP status 200 and "status": false. See Errors for the general format.

Code	What it means	What to do
`9001`	The body is wrong: missing `thread_id` or `thread_ticket_id`, a required field is empty, no status or not exactly one main status, the same status twice, a bad ID, or a row ID that is not on this ticket.	Check the lookups in section 2 and the rules in sections 3 and 4.
`9032`	The conversation, ticket, agent or status was not found.	Check the ID.
`9020`	The conversation, ticket, agent or status belongs to another organization.	Use only your own organization's IDs.

10. Quick checklist

You have the thread_id from the Inbox.

Every required ticket field has a value.

You use ticket status IDs, not thread status IDs.

There is exactly one main status.

Agent IDs come from Get Agents.

Before updating, you read the ticket and send all the rows you want to keep.

What this section doesn't cover

Finding the conversation, its notes, tags and thread status: see the Inbox folder.

Creating your own ticket statuses: not available in the API yet.

Deleting tickets: not available in the API.

Getting started

Getting started with tickets#

1. The big picture#

2. Before you create a ticket: what you need#

3. Ticket fields (the details)#

4. Statuses: one main status, and sub-statuses#

5. Agents#

6. Create a ticket#

7. See tickets#

8. Change a ticket#

9. Common errors#

10. Quick checklist#

What this section doesn't cover#