# Tickets

A customer's request tracked beyond one conversation, with a reference, a state, a promise and every channel's messages. How tickets work, and the API.


A **ticket** is a request that needs following up: a disputed transfer, a complaint, a delivery
that didn't arrive. It has a reference the customer can quote (`AUD-1001`), a type, a state, a
promise ("resolved within 14 days"), and it gathers every conversation about it, on any channel.
Conversations stay where they are; the ticket ties them together.

## The pieces

| | What it is |
|---|---|
| **Reference** | the account's letters and the ticket's number: `AUD-1001`. API paths use the number (`1001`) |
| **Type** | what kind of request (Complaint, Card request, Refund), with its own fields, promise, team and priority. A **complaint** type counts for regulators; a **sensitive** type opens to the customer only once they're verified |
| **State** | in your team's words and the customer's ("In progress" / "We're working on it"), in one of four categories: `submitted`, `in_progress`, `waiting_on_customer`, `resolved` |
| **Promise** | when the type promises to acknowledge and resolve, in hours, calendar days or business days. `due_at` is when it's due; past it and not resolved means **overdue** |
| **Conversations** | every conversation about it. `main_conversation_id` is where it started |
| **Tasks** | work another team does for it, with only the fields and files you share |
| **Trackers** | one incident many customers write about ("card payments failing"): tickets on a tracker are told together and resolved together |

## Every conversation carries its ticket

Every conversation in the API and in [webhooks](/guides/desk-webhooks) has a `ticket` field, `null`
when it's on none:

```json
"ticket": {
  "number": 1001, "reference": "AUD-1001", "title": "Refund for order 88", "kind": "ticket",
  "type": {"id": 2, "name": "Complaint", "complaint": true, "sensitive": true},
  "state": {"name": "In progress", "customer_name": "We're working on it", "category": "in_progress"},
  "assignee_id": 12, "team_id": 3, "priority": "high", "created_via": "texa_ai",
  "due_at": 1792800000, "resolved_at": null, "conversations_count": 2, "open_conversations_count": 1
}
```

Times are Unix seconds. `created_via` says who made it: `person`, `texa_ai`, `rule`, `inbox`,
`customer` or `api`.

## Make one from your system

```bash
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/tickets \
  -H "api_access_token: $TEXA_DESK_TOKEN" -H "Content-Type: application/json" \
  -d '{"conversation_id": 171, "ticket_type_id": 2, "title": "Refund for order 88"}'
```

Without a conversation, give `contact_id` and how the request came in (`channel`: `branch`,
`phone`, `letter`, `in_person`, `other`), for a complaint written at a branch, say. The customer is
told the reference at once, on their channel, in your account's wording.

## Move it along

```bash
# a state
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/tickets/1001/state \
  -H "api_access_token: $TEXA_DESK_TOKEN" -H "Content-Type: application/json" \
  -d '{"ticket_state_id": 9}'
```

- Moving into a **resolved** state asks for the type's required fields first; the refusal says
  which ("Fill in Order reference, Outcome first."). Fill them with `PATCH` and `custom_attributes`.
- Resolving closes the conversations the person sees; `meta.left_open` counts those outside their view.
- **Refusals** are `422 {"error": "<a sentence to show as it is>"}`, in the person's language.

## Who can do what

Tickets follow their conversations: a person sees a ticket when they see one of its conversations.
Making and changing tickets needs `conversation_update`; merging, `ticket_merge`; trackers,
`tracker_manage`; Settings → Tickets, `settings_tickets`; reports, `report_manage` or `report_team`.

## Events

Subscribe a [Texa Desk webhook](/guides/desk-webhooks) to `ticket_created`, `ticket_updated` and
`ticket_merged`. A change to a ticket also sends `conversation_updated` for each of its conversations.

## For regulators

A complaint's register and a regulator's return (CBN, Bank of Ghana) download as CSV:
[complaints register](/api-reference/desk-texa/ticket-reports/complaints-register-as-csv),
[a regulator's return](/api-reference/desk-texa/ticket-reports/a-regulator-s-return-as-csv).

## Reference

Every route: [Tickets API](/api-reference/desk-texa/tickets/list-tickets). Customers follow their own
tickets through the [customer portal](/desk/customer-portal).