Customer Tickets

Your customers' support tickets — the same tickets your team works under Tickets in the oToK app, and that customers open and follow on the workspace's hosted help page or website widget. Over the API your own systems can open tickets, read them with their conversation, answer the customer, and triage (status, priority, category, assignee). Lifecycle changes fire the opt-in ticket.* webhooks.

Every write here does exactly what the same action does inside oToK. A ticket opened here is routed, starts its response target, alerts the team and emails the customer their ticket link like one opened on the help page; a reply here is a real team reply — the ticket moves to Answered, its response target is met, and the customer is emailed. Internal notes and system lines never leave through the API.

All endpoints require authentication. There is no DELETE — close a ticket instead.

Plan feature required: every route on this page requires the Customer tickets feature (customer_tickets, Growth and up) on the workspace's plan. Without it, all calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" (the message embeds customer_tickets) — see feature-gated resource groups.

Errors. Business refusals on these routes use the structured envelope {"error": {"code", "message"}} — key on error.code. Request-validation failures (unknown or malformed fields, a non-UUID path id) use the standard {"statusCode", "message", "error"} shape. Two contact refusals keep their shared shape with a top-level error_code: CONTACT_MERGE_REQUIRED (see contacts) and CONTACT_ANONYMISED — the ticket's contact was anonymised, so the ticket takes no more writes:

{
  "message": "This contact was anonymised — …",
  "error_code": "CONTACT_ANONYMISED",
  "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c"
}

The ticket object

The same object on every route here and in every ticket.* webhook (data.ticket).

Statuses

The message object

The customer-email object (last_customer_email)

The ticket's latest email to the customer and its state — including one that did not go out. null when the ticket has never emailed its customer. Returned only by GET /v1/tickets/:id.

GET /api/v1/tickets

Filters are ANDed.

curl "https://app.otok.io/api/v1/tickets?status=open&assignee=unassigned" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200: { "data": [ …ticket objects… ], "total": 12, "limit": 50, "offset": 0 }. List rows carry no messages.

GET /api/v1/tickets/:id

The ticket object, its last_customer_email, and one page of its conversation — the customer's and the team's messages, never internal notes or system lines.

Paging the conversation. The first answer holds the newest messages; each page is ordered oldest to newest. While messages_has_more is true, call again with messages_before set to messages_next_before to get the page before it.

curl "https://app.otok.io/api/v1/tickets/5b1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5?messages_limit=20" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200:

{
  "id": "5b1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5",
  "number": 1042,
  "number_label": "T-1042",
  "subject": "Can't log in to the course",
  "status": "pending",
  "priority": "normal",
  "category": "Access",
  "source": "api",
  "language": "en",
  "widget_id": null,
  "external_reference": "helpdesk-88213",
  "contact": { "id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c", "name": "Jane Cohen", "email": "jane@example.com", "phone": "+972501234567" },
  "assignee": { "id": "708192a3-b4c5-d6e7-f809-1a2b3c4d5e6f", "name": "Dana Levi", "email": "dana@example.com" },
  "first_response_at": "2026-10-05T09:12:40.000Z",
  "response_target": null,
  "last_message_at": "2026-10-05T09:12:40.000Z",
  "resolved_at": null,
  "closed_at": null,
  "created_at": "2026-10-05T08:57:02.000Z",
  "updated_at": "2026-10-05T09:12:40.000Z",
  "last_customer_email": {
    "kind": "reply",
    "status": "delivered",
    "reason": null,
    "created_at": "2026-10-05T09:12:41.000Z",
    "sent_at": "2026-10-05T09:12:42.000Z",
    "bounced_at": null,
    "complained_at": null
  },
  "messages": [
    {
      "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
      "side": "customer",
      "origin": "api",
      "author": null,
      "body": "I reset my password but the course page still says access denied.",
      "media_url": null,
      "media_filename": null,
      "media_mime_type": null,
      "media_size": null,
      "created_at": "2026-10-05T08:57:02.000Z"
    },
    {
      "id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b",
      "side": "team",
      "origin": "agent",
      "author": { "id": "708192a3-b4c5-d6e7-f809-1a2b3c4d5e6f", "name": "Dana Levi" },
      "body": "Thanks Jane — I've re-enabled your access. Please try again.",
      "media_url": null,
      "media_filename": null,
      "media_mime_type": null,
      "media_size": null,
      "created_at": "2026-10-05T09:12:40.000Z"
    }
  ],
  "messages_has_more": false,
  "messages_next_before": null
}

A ticket in another workspace → 404 ticket_not_found; a non-UUID id → 400.

POST /api/v1/tickets — open a ticket

opened_by.

• customer (default) behaves like a ticket opened on the help page: the workspace's routing rules pick the assignee (unless you name one), the first-response target starts, the team gets its "new ticket" alert, the ticket can enter the inquiry queue (under an intake procedure that enables tickets), and a ticket from a blocked contact is filed silently into spam — no email, no alert, no webhook (the answer shows status: "spam").
• team behaves like a ticket a team member logged on the customer's behalf: none of those.

Either way the opening message's origin is api, the ticket's source is api, and the ticket.created webhook fires (except for spam).

curl -X POST "https://app.otok.io/api/v1/tickets" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
        "contact": { "name": "Jane Cohen", "email": "jane@example.com" },
        "subject": "Can'\''t log in to the course",
        "body": "I reset my password but the course page still says access denied.",
        "category": "Access",
        "external_reference": "helpdesk-88213"
      }'

Response 201: the ticket object with its first page of messages (messages, messages_has_more, messages_next_before — the same shape as GET /v1/tickets/:id) plus:

The answer leaves last_customer_email out: the creation email is sent just after the answer. Read the ticket again to see it.

Idempotency

Send an external_reference and retries are safe. A call carrying a reference that already exists changes nothing — no contact is upserted, no email is sent — and answers the original ticket with duplicate: true and status 200. The person the retry names must be the original ticket's contact (the same contact_id, or an inline contact that resolves to it); the same reference on a different contact is a caller bug and answers 409 external_reference_conflict. Find a ticket by your key with GET /v1/tickets?external_reference=….

Errors

POST /api/v1/tickets/:id/replies — reply to the customer

A real team reply. The ticket moves to Answered (pending) — from any status, resolved and closed included — its response target is met, first_response_at is stamped if this is the first answer, and the customer is emailed that the team replied (once per stretch of unread replies, like an in-app reply). The message's origin is api. Replies are text only.

curl -X POST "https://app.otok.io/api/v1/tickets/5b1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5/replies" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Thanks Jane — your access is back. Please try again.","author_email":"dana@example.com","idempotency_key":"reply-88213-1"}'

Response 201:

Idempotency. Re-sending the same idempotency_key with the same body to the same ticket posts nothing and answers the original reply with duplicate: true (200). The same key with a different body, or on another ticket, answers 409 idempotency_key_mismatch. Without a key, every call posts a new reply.

PATCH /api/v1/tickets/:id — triage

Every field is optional; only what you send changes.

curl -X PATCH "https://app.otok.io/api/v1/tickets/5b1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'

Response 200: the ticket object, plus customer_email_skipped when a resolve made by this call was due to email the customer and that email will not go out. Resolving emails the customer when the workspace sends "resolved" emails; closing and every other change email no one.

Customer emails

Ticket emails go to the customer from the workspace's own verified sender only, and count against the workspace's monthly email allowance. When an email a call triggers will not go out, the answer says why in customer_email_skipped:

A skipped email is still recorded: GET /v1/tickets/:id shows it in last_customer_email with status: "failed" and the same reason. That field also reports emails that left but did not land — bounced, complained, skipped_suppressed (the address is on a suppression list, reason: "suppressed") and other failures (reason: "send_failed").

The ticket's other rules still apply: the customer is emailed a "team replied" message once per stretch of unread replies, and a "resolved" message only when the workspace has those emails switched on.

Automations this fires

A ticket handled here is handled like any other: opening one fires the ticket-created automations (then the ticket-assigned ones when it lands on someone), assigning someone through PATCH fires the ticket-assigned automations, and a resolve fires the ticket-resolved ones. Every change also emits the matching ticket.* webhook.

Related

• Contacts — the identity resolution the inline contact uses
• Webhooks — ticket.created, ticket.message_created, ticket.status_changed, ticket.assigned