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"
}
}
| Field | Required | Description |
|---|---|---|
type | โ | The kind of help needed. See Issue Types. |
description | Free text, up to 5,000 characters. Agents see this before the first message. | |
lat, lng | The traveller's current location. Strongly recommended: it lets the agent find local help immediately. | |
country_code | ISO 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
| Value | Type |
|---|---|
0 | Medical emergency |
10 | Passport / travel documents |
11 | Legal |
20 | Luggage |
21 | Flight |
99 | Other |
Issue Statuses
| Value | Status | Meaning |
|---|---|---|
0 | Collecting details | Newly submitted; not yet picked up by an agent. |
1 | Waiting | The traveller is waiting for help. |
2 | Handling | An agent has been assigned and is working the case. |
3 | Closed | Resolved. Still visible to the traveller. |
4 | Cancelled | Cancelled by the traveller. |
5 | Finished | Ended 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.
| Endpoint | Description |
|---|---|
GET /api/v2/org/:company_id/issues | Issues belonging to your organization. Add all=true to include ended issues. |
GET /api/v2/org/:company_id/issues/:id | A single issue. |
GET /api/v2/issues/:id/conversation | The issue's conversation, including all of its messages. |
GET /api/v2/conversations/:id/messages | The 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_idmust be one of your organization's travellers.creator_idis 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.