Tracking deliveries

All tracking endpoints require the same Bearer token.

5.1 Get failover tracking – GET /otp/failover/{id}

Returns the flow and full delivery story (primary attempt + optional failover step). id can be the flowId (UUID, returned by POST /otp/send-failover) or a message token (primary or failover); we return the same story. For pending/queued Viber/SMS, status is refreshed from Routee when you call this.

GET https://connect.routee.net/failover-otp/otp/failover/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer <your_access_token>

Response (200)

{
  "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Succeeded",
  "statusCode": null,
  "total_cost": 0.0468,
  "steps": [
    {
      "trackingId": "550e8400-e29b-41d4-a716-446655440000",
      "role": "primary",
      "status": "EXPIRED",
      "channel": "viber",
      "phone_number": "306912345671",
      "created_at": "2026-02-16T12:00:00Z",
      "detailed_status": "Expired",
      "price": 0.0093
    },
    {
      "trackingId": "660e8400-e29b-41d4-a716-446655440001",
      "role": "failover",
      "status": "queued",
      "channel": "sms",
      "phone_number": "306912345671",
      "failover_from_message_token": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-02-16T12:02:00Z",
      "price": 0.0375
    }
  ]
}

flowId – Unique flow identifier (UUID). Use this to track the full flow.
status – Flow-level status: InProgress, Succeeded, or Failed (aligned with Routee Failover Service semantics).
statusCode – When status is Failed: 0 = server error, 1 = insufficient balance, 2 = no next step, 3 = not failover triggered.
total_cost – Sum of price across all steps (when available).
steps – Ordered delivery steps: steps[0] is the primary attempt, steps[1] is the failover if sent. Each step has trackingId, role (primary | failover), status, channel, phone_number, and optionally price, latency_ms, country, operator, created_at, delivered_at, detailed_status, error_message, failover_from_message_token.

Flow-level statuses

The status field reflects the outcome of the whole flow (all channel attempts), not a single delivery. It is consistent with the send response: the flow stays InProgress until it has actually ended.

Status	When it is set
InProgress	The flow is still in progress: (1) Only the first step exists so far (failover not yet sent)—even if that step is Delivered, the flow may still send the next step (e.g. SMS after Viber Delivered + TTL with `failoverOnDelivered`); or (2) only the first step exists and it has failed (e.g. UNDELIVERED), but the flow has a next channel (e.g. SMS) that will be or is being tried—status remains InProgress until the failover step exists and its outcome is known; or (3) two steps exist but not all are in a terminal failure state and none has succeeded yet; or (4) when `failoverOnDelivered` is true, two steps exist but the failover step is not yet in a terminal state (e.g. still queued or pending)—status remains InProgress until the failover step reaches Delivered, Sent, or a terminal failure.
Succeeded	The flow has ended with at least one step in a success state (Delivered or Sent). When `failoverOnDelivered` is true and both steps exist, Succeeded is only set once the failover step has reached a terminal state (Delivered, Sent, or a terminal failure); until then the flow stays InProgress even if the primary is Delivered. When failoverOnDelivered is false (or single-step), Succeeded is set as soon as any step is Delivered/Sent.
Failed	All steps that exist are in a terminal failure state (e.g. Failed, Undelivered, Expired, Unsent). If both Viber and SMS fail to deliver, the flow status is Failed.

*When status is Failed, statusCode (if present) gives a more specific reason:

statusCode	Description
0	Server error; check authentication and retry.
1	Insufficient balance; top up the Routee account.
2	No next step; the flow had no further channel to try.
3	Not failover triggered; the status that would trigger the next channel did not occur.

5.2 List deliveries – GET /otp/failover

List and filter deliveries.

GET https://connect.routee.net/failover-otp/otp/failover?status=DELIVERED&tag=login&limit=50&offset=0
Authorization: Bearer <your_access_token>

Query parameters

Parameter	Type	Description
status	string	Filter by status (e.g. Delivered, Failed, Undelivered)
tag	string	Filter by tag/label (partial match; matches the `label` field from the flow step).
phone_number	string	Filter by destination (partial match)
flow_id	string	Filter by flow ID (UUID); returns all deliveries in that flow
limit	integer	Max results (default 50, max 200)
offset	integer	Pagination offset (default 0)

Response (200) – total, limit, offset, and results (array of delivery objects). Each result includes flowId and role (primary | failover).