POST /v1/tickets

Open a ticket on a conversation, with a subject and optionally a priority, category and assignee.

Opens a new ticket in a person’s conversation, as a team member starting one in the Inbox would. A conversation has one live ticket at a time: if one is already open or pending there, it is solved first. The conversation is opened too if it was closed. The ticket’s history names the change “API · ” and the key’s name.

Needs the tickets:write scope.

Body

Field	Type	Required	Notes
conversation	string	Yes	The conversation to open it on, by the id /v1/conversations uses: the contact’s id. The contact must already have a conversation.
subject	string	No	What it is about. Up to 200 characters; “New ticket” when left out.
priority	string	No	normal, high or urgent. The conversation’s when left out.
category	integer	No	One of your categories’ ids, or null for none.
assignee	string	No	A team member’s email, or null for nobody. The conversation’s assignee when left out.

Priority and assignee are the conversation’s: setting them here changes the conversation too.

Send an Idempotency-Key header to open it once however often the request is retried.

Request

cURL

curl -X POST "https://api.fireflo.au/v1/tickets" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Idempotency-Key: ticket-a1042" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "3f6b2a1e-8c4d-4e2a-9b7f-5d1c0e8a9f42",
    "subject": "Order A-1042 not delivered",
    "priority": "high",
    "category": 4,
    "assignee": "[e-mail]"
  }'

Response

201 Created — the ticket. A ticket.opened webhook event follows, and ticket.solved for one it solved.

{
  "id": "b84f2c10-5e7a-4c3d-9a61-0f2d7e9c4a18",
  "number": 1042,
  "subject": "Order A-1042 not delivered",
  "status": "open",
  "priority": "high",
  "assignee": {
    "name": "Priya Nair",
    "email": "[e-mail]"
  },
  "category": {
    "id": 4,
    "name": "Delivery",
    "colour": "info"
  },
  "contact": {
    "id": "3f6b2a1e-8c4d-4e2a-9b7f-5d1c0e8a9f42",
    "name": "Asha Rao",
    "phone": "[phone]"
  },
  "conversation": "3f6b2a1e-8c4d-4e2a-9b7f-5d1c0e8a9f42",
  "source": "staff",
  "handled_by": "",
  "resolution": "",
  "summary": "",
  "opened_at": "2026-10-06T10:15:03+05:30",
  "first_response_at": null,
  "last_activity_at": "2026-10-06T10:15:03+05:30",
  "solved_at": null,
  "closed_at": null
}

Errors

Every refusal is {"error": {"code", "message", "field"}}; field is there when one input is at fault.

Status	Error code	When
400	invalid_request	An input is wrong (field names it): conversation is missing or no contact has that id, the subject is too long, an unknown priority, no category with that id, or no one in your team has that email.
400	invalid_json	The body isn’t valid JSON.
409	no_conversation	The contact has no conversation yet: a ticket lives in a thread.
409	invalid_state	Tickets are switched off in the account’s Ticket settings.
404	module_off	The account’s plan doesn’t include Tickets.
403	scope_missing	The key doesn’t have the tickets:write scope.

Any request can also be refused for its key, its account or its rate (key_required, invalid_key, account_suspended, plan_excludes_api, address_not_allowed, rate_limited); see the overview.