Skip to main content

Issues

An issue is an assistance case. Creating one puts the traveller in front of an assistance agent and opens the chat conversation they'll talk in.

All requests on this page are made as the traveller (see Authentication) unless stated otherwise:

Authorization: TKN <traveller authentication_token>
Organization: <company_id>
Content-Type: application/json

Create An Issue

POST /api/v2/issues
{
"issue": {
"type": 10,
"description": "My passport was stolen at the train station.",
"lat": 41.3874,
"lng": 2.1686,
"country_code": "ES"
}
}
FieldRequiredDescription
typeโœ…The kind of help needed. See Issue Types.
descriptionFree text, up to 5,000 characters. Agents see this before the first message.
lat, lngThe traveller's current location. Strongly recommended: it lets the agent find local help immediately.
country_codeISO 3166-1 alpha-2 code of the country the traveller is in.

Sitata routes the issue to the assistance provider configured for your organization, alerts the on-call agents, and starts the response SLA clock. A conversation is created automatically, seeded with a "please stand by" announcement. The response is the new issue:

{
"id": "0d9b3a40-5f3c-4c9e-8a7e-2f6a1b8c9d01",
"human_id": "8C9D01",
"conversation_id": "a4e2c1d7-9b8f-4e6a-b5c3-1d2e3f4a5b6c",
"type": 10,
"status": 0,
"severity": 1,
"description": "My passport was stolen at the train station.",
"lat": 41.3874,
"lng": 2.1686,
"country_code": "ES",
"affected_id": "6b0c6f8e-2b1f-4a8e-9d55-0d6f1d3c2a10",
"current_handler_id": null,
"created_at": "2026-10-12T14:03:11Z",
"updated_at": "2026-10-12T14:03:11Z",
"ended_at": null,
...
}

Keep the conversation_id: it's what you'll join on the real-time socket.

Issue Types

ValueType
0Medical emergency
10Passport / travel documents
11Legal
20Luggage
21Flight
99Other

Issue Statuses

ValueStatusMeaning
0Collecting detailsNewly submitted; not yet picked up by an agent.
1WaitingThe traveller is waiting for help.
2HandlingAn agent has been assigned and is working the case.
3ClosedResolved. Still visible to the traveller.
4CancelledCancelled by the traveller.
5FinishedEnded automatically after 7 days without activity (the traveller is warned after 6).

An issue's status is managed by Sitata and its agents. Treat it as read-only in your integration.

List And View Issues

GET /api/v2/issues               # the traveller's open issues
GET /api/v2/issues?status=closed # closed, cancelled and finished issues
GET /api/v2/issues?all=true # every issue, whatever its status
GET /api/v2/issues/:id
GET /api/v2/issues/unread_count # {"unread_count": 3} across open issues

Each issue in the list includes an unread_count: how many messages in its conversation the traveller hasn't read yet. Lists are paginated with the standard pagination headers.

End An Issue

The traveller can cancel an issue they no longer need help with:

PATCH /api/v2/issues/:id/cancel

Otherwise, Sitata's assistance agents close the issue once the case is resolved. Closing an issue and changing its status are reserved for agents: requests from travellers or organizations to close an issue, or to send a different status, are rejected with 401.

tip

Ending an issue doesn't lock its conversation. If the traveller sends another message after the issue is closed or finished, the issue reopens automatically and returns to the agents' queue, so travellers can always get back in touch on the same thread.

Organization-Side Endpoints

These endpoints use your organization token from your servers.

EndpointDescription
GET /api/v2/org/:company_id/issuesIssues belonging to your organization. Add all=true to include ended issues.
GET /api/v2/org/:company_id/issues/:idA single issue.
GET /api/v2/issues/:id/conversationThe issue's conversation, including all of its messages.
GET /api/v2/conversations/:id/messagesThe conversation's messages, newest first, paginated. See Messaging.

Creating Issues As Your Organization

POST /api/v2/org/:company_id/issues
{
"issue": {
"type": 99,
"description": "Customer called our hotline about a cancelled tour.",
"affected_id": "<traveller id>",
"creator_id": "<id of the staff user raising the case>"
}
}
info

Issues created this way are handled by Sitata's assistance team, exactly like issues travellers create themselves: agents are alerted immediately and the case enters their queue. They also belong to your organization, so you can follow them with the organization endpoints above.

  • affected_id must be one of your organization's travellers.
  • creator_id is required when you use your organization token, and must belong to your organization (as a traveller or as staff). When a staff user's token is used, that user is the creator.
  • Both the traveller and the creator are added to the issue's conversation.

See the full reference for Issues and Organization Issues.