Inspect planned and recorded journey checkpoints and submit authorized checkpoint observations.
GET /api/v1/checkpoints/get_checkpoint_list get_checkpoint_list checkpoints:read Tier a ₦100.00
List the planned checkpoints and the most recent recorded checkpoints for a journey.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the journey whose planned and recorded checkpoints are listed.
State constraints The journey must exist and be owned by the requesting organization linked ride owner. Recorded checkpoints are capped at the 200 most recent rows ordered by recording time. Idempotency Safe read; no side effects.
Response Planned and recorded checkpoints for the journey.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"planned_checkpoints": [
{
"id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"checkpoint_number": 2,
"checkpoint_name": "Sagamu interchange",
"planned_offset_minutes": 50,
"planned_for": "2026-09-28T09:20:00.000Z"
}
],
"recorded_checkpoints": [
{
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"checkpoint_type": "planned",
"checkpoint_number": 2,
"planned_for": "2026-09-28T09:20:00.000Z",
"recorded_at": "2026-09-28T09:24:10.000Z",
"status": "completed",
"gps": {
"lat": 6.5244,
"lng": 3.3792,
"accuracy_m": 12
},
"notes": "Departed on schedule with all passengers aboard."
}
]
}
}Errors Code HTTP Cause INVALID_REQUEST 400 journey_id is missing or is not a valid resource identifier. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:read scope or the organization is not linked to an ORN platform account.
Next steps GET /api/v1/checkpoints/retrieve_checkpoint_state retrieve_checkpoint_state checkpoints:read Tier c ₦300.00
Return the current state of one checkpoint including its type, status, timing and GPS reading.
Parameters Name In Type Required Description checkpoint_id query string (uuid) Yes Identifier of the checkpoint to inspect.
State constraints The checkpoint must exist and its parent journey must be owned by the requesting organization linked ride owner. Idempotency Safe read; no side effects.
Response Current state of one checkpoint.
{
"data": {
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"checkpoint_type": "planned",
"checkpoint_number": 2,
"planned_for": "2026-09-28T09:20:00.000Z",
"recorded_at": "2026-09-28T09:24:10.000Z",
"status": "completed",
"gps": {
"lat": 6.5244,
"lng": 3.3792,
"accuracy_m": 12
},
"notes": "Departed on schedule with all passengers aboard."
}
}Errors Code HTTP Cause INVALID_REQUEST 400 checkpoint_id is missing or is not a valid resource identifier. RESOURCE_NOT_FOUND 404 No checkpoint owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:read scope or the organization is not linked to an ORN platform account.
Next steps GET /api/v1/checkpoints/retrieve_checkpoint_eta retrieve_checkpoint_eta checkpoints:read Tier c ₦300.00
Return the planned time of a checkpoint and the next outstanding planned checkpoint on its journey.
Parameters Name In Type Required Description checkpoint_id query string (uuid) Yes Identifier of the checkpoint whose planned timing is inspected.
State constraints The checkpoint must exist and its parent journey must be owned by the requesting organization linked ride owner. next_planned is the earliest checkpoint of type planned with status planned whose checkpoint_number is greater than or equal to the current checkpoint number, or null when none exists. Idempotency Safe read; no side effects.
Response Planned time and the next pending checkpoint.
{
"data": {
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"planned_for": "2026-09-28T09:20:00.000Z",
"next_planned": {
"checkpoint_id": "f6a5b4c3-7777-4aaa-9bbb-8c9d0e1f2a3b",
"checkpoint_number": 3,
"planned_for": "2026-09-28T10:05:00.000Z"
}
}
}Errors Code HTTP Cause INVALID_REQUEST 400 checkpoint_id is missing or is not a valid resource identifier. RESOURCE_NOT_FOUND 404 No checkpoint owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:read scope or the organization is not linked to an ORN platform account.
Next steps GET /api/v1/checkpoints/retrieve_checkpoint_history retrieve_checkpoint_history checkpoints:read Tier c ₦350.00
Return the most recent recorded checkpoints for a journey, capped at 200 rows.
Parameters Name In Type Required Description journey_id query string (uuid) Yes Identifier of the journey whose recorded checkpoint history is returned.
State constraints The journey must exist and be owned by the requesting organization linked ride owner. History is capped at the 200 most recent checkpoints ordered by recording time descending. Idempotency Safe read; no side effects.
Response Recorded checkpoints for the journey, newest first.
{
"data": {
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"checkpoints": [
{
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"checkpoint_type": "planned",
"checkpoint_number": 2,
"planned_for": "2026-09-28T09:20:00.000Z",
"recorded_at": "2026-09-28T09:24:10.000Z",
"status": "completed",
"gps": {
"lat": 6.5244,
"lng": 3.3792,
"accuracy_m": 12
},
"notes": "Departed on schedule with all passengers aboard."
}
]
}
}Errors Code HTTP Cause INVALID_REQUEST 400 journey_id is missing or is not a valid resource identifier. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:read scope or the organization is not linked to an ORN platform account.
Next steps GET /api/v1/checkpoints/retrieve_checkpoint_evidence_summary retrieve_checkpoint_evidence_summary checkpoints:read Tier c ₦400.00
Return the evidence summary of one checkpoint covering status, recording time, GPS position and notes.
Parameters Name In Type Required Description checkpoint_id query string (uuid) Yes Identifier of the checkpoint whose evidence summary is returned.
State constraints The checkpoint must exist and its parent journey must be owned by the requesting organization linked ride owner. Idempotency Safe read; no side effects.
Response Recorded evidence attached to one checkpoint observation.
{
"data": {
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"status": "completed",
"recorded_at": "2026-09-28T09:24:10.000Z",
"gps": {
"lat": 6.5244,
"lng": 3.3792,
"accuracy_m": 12
},
"notes": "Departed on schedule with all passengers aboard."
}
}Errors Code HTTP Cause INVALID_REQUEST 400 checkpoint_id is missing or is not a valid resource identifier. RESOURCE_NOT_FOUND 404 No checkpoint owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:read scope or the organization is not linked to an ORN platform account.
Next steps POST /api/v1/checkpoints/submit_authorized_checkpoint_observation submit_authorized_checkpoint_observation checkpoints:write Tier c ₦400.00
Record an authorized partner observation for a journey checkpoint through the authoritative recorder.
Parameters Name In Type Required Description journey_id body string (uuid) Yes Identifier of the journey the observation belongs to. checkpoint_number body number Yes Checkpoint number the observation applies to. status body string Yes Observation outcome, one of triggered, completed, missed or escalated. planned_for body string No Optional planned timestamp to associate with the observation. gps_lat body number No Optional latitude of the observation position. gps_lng body number No Optional longitude of the observation position. gps_accuracy_m body number No Optional GPS accuracy in meters for the observation position. notes body string No Optional free-form notes recorded with the observation.
State constraints The journey must exist and be owned by the requesting organization linked ride owner. status must be one of triggered, completed, missed or escalated. The observation is recorded as an actual checkpoint on the journey. Idempotency Not idempotent — retrying may append a duplicate observation.
Response The recorded observation. checkpoint_type is always "actual" for submissions.
{
"data": {
"checkpoint_id": "b1a2c3d4-1111-4aaa-8bbb-2c3d4e5f6a7b",
"journey_id": "0d0b6f2e-6b1a-4f3e-9a4c-1f2e3d4c5b6a",
"checkpoint_type": "actual",
"checkpoint_number": 2,
"status": "completed"
}
}Errors Code HTTP Cause INVALID_REQUEST 400 The body is not valid JSON, a required field is missing or malformed, the status is not an allowed value, or the observation was rejected by the platform. RESOURCE_NOT_FOUND 404 No journey owned by the requesting organization matches the supplied identifier. CAPABILITY_NOT_AUTHORIZED 403 The API key lacks the checkpoints:write scope or the organization is not linked to an ORN platform account. FORBIDDEN 403 Write operations are refused for sandbox environment keys.
Events checkpoint.observation_recorded
Next steps