Create incident

POST

/incidents

Report an emergency on behalf of one of your users.
Sety immediately dispatches the nearest available responder.

Categories

sos — Panic button, personal danger

vehicle — Hijack, road robbery, accident

location_threat — Robbery or violence at a specific place

medical — Injury or health emergency

Idempotency: Pass idempotency_key (e.g. your trip ID or session ID)
to safely retry. Duplicate keys return the existing incident.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Existing incident returned (idempotent — key already used)

Body

🟢201

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

Request Example

Shell

JavaScript

Java

Swift

cURL

SOS panic buttonVehicle hijackArmed robbery at ATM

curl --location --request POST '/incidents' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "category": "sos",
    "severity": "critical",
    "idempotency_key": "session_abc123",
    "subject": {
        "name": "Amaka Obi",
        "phone": "+2348012345678",
        "reference": "USER-9921"
    },
    "location": {
        "coordinates": [
            3.3792,
            6.5244
        ],
        "address": "14 Bourdillon Road, Ikoyi, Lagos"
    }
}'

Response Example

200 - Example 1

{
    "incident": {
        "incident_id": "inc_a1b2c3d4e5f6g7h8",
        "idempotency_key": "string",
        "category": "sos",
        "severity": "low",
        "status": "created",
        "subject": {
            "name": "Amaka Obi",
            "phone": "+2348012345678",
            "email": "[email protected]",
            "reference": "TRIP-44821",
            "metadata": {
                "vehicle_plate": "LND-204-KJA",
                "driver_name": "Olu Babs"
            }
        },
        "title": "string",
        "description": "string",
        "location": {
            "coordinates": [
                3.3792,
                6.5244
            ],
            "address": "14 Bourdillon Road, Ikoyi, Lagos",
            "landmark": "Gate B — North entrance"
        },
        "resolution_outcome": "handled",
        "resolution_notes": "string",
        "is_drill": true,
        "timeline": [
            {
                "status": "string",
                "event": "created",
                "message": "string",
                "timestamp": "2019-08-24T14:15:22.123Z"
            }
        ],
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z",
        "resolved_at": "2019-08-24T14:15:22.123Z",
        "cancelled_at": "2019-08-24T14:15:22.123Z"
    },
    "idempotent": true
}

Modified at 2026-03-10 02:58:15

Health check

List incidents