Driver API

Driver availability, location, trip states and payout settings.

Interactive test consolePaste a dedicated development token below. It stays in this browser tab and is sent only to the API endpoint you test.

Bearer token

Frontend integration guide

Use the endpoint cards below as the source of truth for request methods, authentication and test payloads. Keep credentials in secure storage and send bearer tokens only over HTTPS.

Mutating requests should include a unique Idempotency-Key. Render API status and error codes explicitly, and refetch state after reconnecting.

REST response contract

Every response is JSON: { success, data, error }. When success is true, read data. When it is false, use error.code for app logic and error.message for safe UI text.

HTTP	Meaning	Frontend action
`200`	Request succeeded.	Render `data`.
`201`	Resource created.	Persist its returned ID/state.
`202`	Accepted for asynchronous work.	Show pending; it is not authentication.
`400`	Invalid request or business rule.	Show `error.message` and field details.
`401`	Token missing, expired or invalid.	Refresh session or sign in.
`403`	Access denied.	Do not retry.
`404`	Unavailable or hidden resource.	Return safely and refresh state.
`409`	State conflict/duplicate/expired resource.	Refetch; do not blindly retry.
`422`	Semantically invalid input.	Highlight the field.
`429`	Rate limited.	Back off, respecting `Retry-After`.
`500`	Unexpected server failure.	Offer a safe retry.

Stable codes: VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, TRIP_ACCESS_DENIED, RIDER_ACTION_RATE_LIMITED and OTP_RATE_LIMITED. Each endpoint guide adds any relevant business codes.

Money and JSON format

All NGN monetary fields ending in Minor are expressed in kobo, not naira. For example, 246500 means ₦2,465; divide by 100 for display. JSON body editors are automatically pretty-printed when valid JSON is entered.

POST/api/v1/auth/driver/onboarding/otp/request

Public

Request driver email or phone OTP

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/auth/driver/onboarding/otp/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"assignedId":"CRZ-ABC-0001","channel":"email"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"assignedId":"CRZ-ABC-0001","channel":"email"}''')
response = requests.post(BASE_URL + '/api/v1/auth/driver/onboarding/otp/request',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"assignedId":"CRZ-ABC-0001","channel":"email"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/auth/driver/onboarding/otp/request');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/auth/driver/onboarding/otp/request' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"assignedId":"CRZ-ABC-0001","channel":"email"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/auth/driver/onboarding/otp/verify

Public

Verify driver OTP and receive 24-hour access token

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/auth/driver/onboarding/otp/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"assignedId":"CRZ-ABC-0001","code":"123456"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"assignedId":"CRZ-ABC-0001","code":"123456"}''')
response = requests.post(BASE_URL + '/api/v1/auth/driver/onboarding/otp/verify',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"assignedId":"CRZ-ABC-0001","code":"123456"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/auth/driver/onboarding/otp/verify');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/auth/driver/onboarding/otp/verify' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"assignedId":"CRZ-ABC-0001","code":"123456"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/me

Bearer token

Driver profile

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/me', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/me',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/me');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/me' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/home

Bearer token

Driver home dashboard snapshot

Endpoint guide What to send, parse and expect

Why it exists

Returns the driver-home snapshot: readiness, active trip, earnings, completed rides, distance and rating.

Before you call

Call after authentication and whenever the app resumes.

Request fields

No JSON body; identity is derived from bearer authentication.

What to parse

Render readiness.blockers before enabling Online. Monetary Minor values are kobo.

Expected result

200 returns the current dashboard source of truth.

Important

The driver cannot calculate or modify this server-owned snapshot.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/home', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/home',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/home');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/home' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/readiness

Bearer token

Check online eligibility and blockers

Endpoint guide What to send, parse and expect

Why it exists

Explains whether a driver can go online and every blocker preventing it.

Before you call

Call before displaying/enabling the Online switch.

Request fields

No body. The server checks approved documents, active vehicle, battery and fresh location.

What to parse

If ready is false, render each blocker message and resolve it before PATCH status.

Expected result

200 returns readiness whether or not the driver is eligible.

Important

The same checks are enforced again when the driver requests ONLINE.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/readiness', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/readiness',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/readiness');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/readiness' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

PATCH/api/v1/driver/dispatch-preferences

Bearer token

Set pickup range and manual/auto offers

Endpoint guide What to send, parse and expect

Why it exists

Sets pickup range and manual/auto offer behaviour.

Before you call

AUTO can be selected only after fleet enables driver_auto_accept.

Request fields

pickupRadiusKm is 1–50; offerMode is MANUAL or AUTO.

What to parse

Use returned preferences. The range is enforced while ranking drivers for every trip.

Expected result

200 confirms changes; 409 AUTO_ACCEPT_DISABLED means remain Manual.

Important

Clients cannot make the driver eligible outside the saved range.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/dispatch-preferences', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"pickupRadiusKm":10,"offerMode":"MANUAL"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"pickupRadiusKm":10,"offerMode":"MANUAL"}''')
response = requests.patch(BASE_URL + '/api/v1/driver/dispatch-preferences',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"pickupRadiusKm":10,"offerMode":"MANUAL"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/dispatch-preferences');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X PATCH '<base-url>/api/v1/driver/dispatch-preferences' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"pickupRadiusKm":10,"offerMode":"MANUAL"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

PATCH/api/v1/driver/status

Bearer token

Set ONLINE or OFFLINE

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/status', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"status":"ONLINE"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"status":"ONLINE"}''')
response = requests.patch(BASE_URL + '/api/v1/driver/status',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"status":"ONLINE"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/status');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X PATCH '<base-url>/api/v1/driver/status' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"status":"ONLINE"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/offers

Bearer token

Read current expiring driver offers

Endpoint guide What to send, parse and expect

Why it exists

Lists only active, unexpired offers created for the authenticated driver.

Before you call

Set driver status ONLINE. Connect Socket.IO first and handle driver:trip_offer, then use this endpoint after reconnecting or app resume.

Request fields

No request body. The API derives the driver from the bearer token.

What to parse

Render each offer until expiresAt. Do not cache an offer after an accept or decline response.

Expected result

200 returns the current driver-owned offers.

Important

An offer is not a trip assignment; only the assigned driver may view or respond to it.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/offers', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/offers',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/offers');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/offers' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/offers/:id/respond

Bearer token

Accept or decline an expiring driver offer

Endpoint guide What to send, parse and expect

Why it exists

Atomically accepts or declines a single expiring trip offer.

Before you call

Call only from an offer returned by GET offers or a driver:trip_offer socket event. Disable both buttons once tapped.

Request fields

Replace :id with the offer UUID. decision is ACCEPT or DECLINE.

What to parse

On ACCEPT render assigned trip details; on DECLINE discard the offer. OFFER_EXPIRED and OFFER_NOT_AVAILABLE mean refetch offers.

Expected result

200 returns assignment or reassignment outcome; 409 prevents a late or duplicate response.

Important

The server rechecks offer owner, expiry, driver availability and vehicle availability within one transaction.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/offers/:id/respond', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"decision":"ACCEPT"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"decision":"ACCEPT"}''')
response = requests.post(BASE_URL + '/api/v1/driver/offers/:id/respond',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"decision":"ACCEPT"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/offers/:id/respond');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/offers/:id/respond' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"decision":"ACCEPT"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/location

Bearer token

Send verified GPS location

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/location', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"latitude":4.8156,"longitude":7.0498})
});
const result = await response.json();

Python

payload = json.loads(r'''{"latitude":4.8156,"longitude":7.0498}''')
response = requests.post(BASE_URL + '/api/v1/driver/location',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"latitude":4.8156,"longitude":7.0498}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/location');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/location' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"latitude":4.8156,"longitude":7.0498}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/trips/active

Bearer token

Active trips

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/active', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/trips/active',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/active');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/trips/active' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/trips/:id/state

Bearer token

Transition a driver trip state

Endpoint guide What to send, parse and expect

Why it exists

Use this endpoint to perform the action described above.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

The JSON editor contains a runnable example. Required field rules are returned as error.details.fieldErrors when validation fails.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/:id/state', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"status":"DRIVER_EN_ROUTE"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"status":"DRIVER_EN_ROUTE"}''')
response = requests.post(BASE_URL + '/api/v1/driver/trips/:id/state',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"status":"DRIVER_EN_ROUTE"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/:id/state');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/trips/:id/state' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"status":"DRIVER_EN_ROUTE"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/trips/:id/pickup/verify

Bearer token

Verify rider pickup PIN or QR

Endpoint guide What to send, parse and expect

Why it exists

Verifies the rider’s PIN or QR at pickup and atomically advances the ride to PASSENGER_ONBOARD.

Before you call

This is available only when the fleet has pickup verification enabled and the driver has already set DRIVER_ARRIVED.

Request fields

Replace :id with the assigned trip UUID. Send either pin (four digits) or qrPayload read by the driver’s scanner.

What to parse

Use data.trip.status as the new source of truth. A repeat tap returns alreadyVerified:true and is safe.

Expected result

200 confirms boarding. 400 is an invalid PIN/QR; 409 identifies an unavailable state, disabled feature or missing arrival.

Important

The rider-only credential never appears in driver detail APIs and the driver cannot choose another trip’s PIN.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/:id/pickup/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"pin":"1234"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"pin":"1234"}''')
response = requests.post(BASE_URL + '/api/v1/driver/trips/:id/pickup/verify',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"pin":"1234"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/:id/pickup/verify');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/trips/:id/pickup/verify' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"pin":"1234"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/earnings

Bearer token

Driver earnings and commission

Endpoint guide What to send, parse and expect

Why it exists

Returns server-calculated gross, commission, net and completed trips.

Before you call

Optionally add ?period=TODAY, LAST_7_DAYS or LAST_30_DAYS.

Request fields

No JSON body. Values ending in Minor are kobo.

What to parse

Show gross, commission and net separately; this is not a payout instruction.

Expected result

200 returns summary and trip rows.

Important

Only the caller’s completed trips are included.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/earnings', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/earnings',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/earnings');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/earnings' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/score

Bearer token

Driver dispatch score and audit events

Endpoint guide What to send, parse and expect

Why it exists

Shows dispatch score, rider rating and an immutable score-event history.

Before you call

Use this for transparent driver education.

Request fields

No body.

What to parse

Score is 0–1000; ranking weights reliability 55%, rating 25% and proximity 20%.

Expected result

200 returns score and events.

Important

Only trusted backend actions write score events.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/score', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/score',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/score');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/score' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/fraud-signals

Bearer token

Driver-visible risk signals

Endpoint guide What to send, parse and expect

Why it exists

Lists non-sensitive fraud/operational flags affecting the signed-in driver.

Before you call

Use for transparent account-health and support screens.

Request fields

No body.

What to parse

Render status and safe detail. Do not infer internal fraud thresholds.

Expected result

200 returns caller-owned records.

Important

Drivers cannot create, clear or alter signals.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/fraud-signals', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/fraud-signals',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/fraud-signals');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/fraud-signals' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/messages

Bearer token

Read authorised driver messages

Endpoint guide What to send, parse and expect

Why it exists

Lets the assigned driver read and send messages only within an authorised active trip.

Before you call

The rider must be assigned to the driver. Use the trip id from the driver active-trips response.

Request fields

POST accepts tripId and body; the server derives the rider recipient, so do not send recipientId.

What to parse

Render messages only in the matching trip conversation and subscribe to message:received for delivery.

Expected result

GET 200 returns the driver message inbox; POST 201 creates the trip message.

Important

The backend rejects messages for a trip assigned to another driver.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/messages', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/messages',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/messages');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/messages' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/messages

Bearer token

Send an authorised message to active rider

Endpoint guide What to send, parse and expect

Why it exists

Lets the assigned driver read and send messages only within an authorised active trip.

Before you call

The rider must be assigned to the driver. Use the trip id from the driver active-trips response.

Request fields

POST accepts tripId and body; the server derives the rider recipient, so do not send recipientId.

What to parse

Render messages only in the matching trip conversation and subscribe to message:received for delivery.

Expected result

GET 200 returns the driver message inbox; POST 201 creates the trip message.

Important

The backend rejects messages for a trip assigned to another driver.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"tripId":"uuid","body":"I am approaching pickup."})
});
const result = await response.json();

Python

payload = json.loads(r'''{"tripId":"uuid","body":"I am approaching pickup."}''')
response = requests.post(BASE_URL + '/api/v1/driver/messages',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"tripId":"uuid","body":"I am approaching pickup."}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/messages');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/messages' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"tripId":"uuid","body":"I am approaching pickup."}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/support/tickets

Bearer token

List driver support tickets

Endpoint guide What to send, parse and expect

Why it exists

Creates/lists driver-owned support tickets for non-emergency issues.

Before you call

Use for payment, vehicle, account or rider issues.

Request fields

POST accepts category, subject, details, priority and optional owned tripId.

What to parse

Persist the returned ticket id/status for support UI.

Expected result

GET 200; POST 201.

Important

A driver can attach only their own trip.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/support/tickets', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/support/tickets',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/support/tickets');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/support/tickets' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/support/tickets

Bearer token

Open a driver support ticket

Endpoint guide What to send, parse and expect

Why it exists

Creates/lists driver-owned support tickets for non-emergency issues.

Before you call

Use for payment, vehicle, account or rider issues.

Request fields

POST accepts category, subject, details, priority and optional owned tripId.

What to parse

Persist the returned ticket id/status for support UI.

Expected result

GET 200; POST 201.

Important

A driver can attach only their own trip.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/support/tickets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"category":"PAYMENT","subject":"Transfer pending","details":"Trip payment has not appeared.","priority":"HIGH"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"category":"PAYMENT","subject":"Transfer pending","details":"Trip payment has not appeared.","priority":"HIGH"}''')
response = requests.post(BASE_URL + '/api/v1/driver/support/tickets',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"category":"PAYMENT","subject":"Transfer pending","details":"Trip payment has not appeared.","priority":"HIGH"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/support/tickets');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/support/tickets' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"category":"PAYMENT","subject":"Transfer pending","details":"Trip payment has not appeared.","priority":"HIGH"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/safety/incidents

Bearer token

Raise driver SOS or safety incident

Endpoint guide What to send, parse and expect

Why it exists

Raises a driver SOS or safety incident for fleet operations.

Before you call

In immediate danger call emergency services first, then send current coordinates where available.

Request fields

POST type, description and optional own trip/location. SOS/collision are CRITICAL.

What to parse

After 201 confirm, retain the emergency action and await operational follow-up.

Expected result

201 creates a durable auditable incident.

Important

Trip ownership is verified and severity is server determined.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/safety/incidents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"type":"SOS","description":"I need urgent help","latitude":4.8156,"longitude":7.0498})
});
const result = await response.json();

Python

payload = json.loads(r'''{"type":"SOS","description":"I need urgent help","latitude":4.8156,"longitude":7.0498}''')
response = requests.post(BASE_URL + '/api/v1/driver/safety/incidents',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"type":"SOS","description":"I need urgent help","latitude":4.8156,"longitude":7.0498}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/safety/incidents');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/safety/incidents' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"type":"SOS","description":"I need urgent help","latitude":4.8156,"longitude":7.0498}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/remittance-balance

Bearer token

Read cash commission debt and online block state

Endpoint guide What to send, parse and expect

Why it exists

Calculates the authenticated driver cash-trip commission debt to their fleet and tells the app if ONLINE is blocked.

Before you call

Call before enabling Online and after a fleet reviews a payment.

Request fields

No body. All values ending in Minor are kobo.

What to parse

Use outstandingMinor and blocked. The server, not the app, rejects ONLINE when the policy threshold is reached.

Expected result

200 returns the debt, submitted remittances and policy.

Important

Only confirmed cash collections and APPROVED remittances affect the balance.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/remittance-balance', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/remittance-balance',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/remittance-balance');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/remittance-balance' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/remittances

Bearer token

List driver remittances

Endpoint guide What to send, parse and expect

Why it exists

Lists or submits a driver-to-fleet cash commission remittance for fleet finance review.

Before you call

The driver pays the fleet, then submits its payment reference. A fleet approval is required before debt reduces.

Request fields

POST amountMinor, paymentReference and optional note. Amount must not exceed outstanding debt.

What to parse

Render SUBMITTED as pending review and APPROVED as settled.

Expected result

GET 200; POST 201.

Important

The backend owns the debt calculation and rejects over-remittance.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/remittances', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/remittances',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/remittances');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/remittances' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/remittances

Bearer token

Submit cash commission remittance

Endpoint guide What to send, parse and expect

Why it exists

Lists or submits a driver-to-fleet cash commission remittance for fleet finance review.

Before you call

The driver pays the fleet, then submits its payment reference. A fleet approval is required before debt reduces.

Request fields

POST amountMinor, paymentReference and optional note. Amount must not exceed outstanding debt.

What to parse

Render SUBMITTED as pending review and APPROVED as settled.

Expected result

GET 200; POST 201.

Important

The backend owns the debt calculation and rejects over-remittance.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/remittances', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"amountMinor":50000,"paymentReference":"TRF-12345"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"amountMinor":50000,"paymentReference":"TRF-12345"}''')
response = requests.post(BASE_URL + '/api/v1/driver/remittances',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"amountMinor":50000,"paymentReference":"TRF-12345"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/remittances');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/remittances' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"amountMinor":50000,"paymentReference":"TRF-12345"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

PATCH/api/v1/driver/profile

Bearer token

Update the signed-in driver profile

Endpoint guide What to send, parse and expect

Why it exists

Updates the driver name in both the driver and account records.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

Send at least firstName or lastName.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

200 returns the refreshed profile.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/profile', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"firstName":"Jane","lastName":"Doe"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"firstName":"Jane","lastName":"Doe"}''')
response = requests.patch(BASE_URL + '/api/v1/driver/profile',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"firstName":"Jane","lastName":"Doe"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/profile');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X PATCH '<base-url>/api/v1/driver/profile' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"firstName":"Jane","lastName":"Doe"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/devices

Bearer token

List registered driver devices

Endpoint guide What to send, parse and expect

Why it exists

Lists only devices registered by the signed-in driver.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

No body.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

200 returns device settings.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/devices', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/devices',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/devices');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/devices' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

PUT/api/v1/driver/devices

Bearer token

Endpoint guide What to send, parse and expect

Why it exists

Safely upserts a device registration for notifications.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

deviceId, platform and optional pushToken.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

200 returns the registered device.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/devices', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"deviceId":"ios-installation-id","platform":"IOS","notificationsEnabled":true})
});
const result = await response.json();

Python

payload = json.loads(r'''{"deviceId":"ios-installation-id","platform":"IOS","notificationsEnabled":true}''')
response = requests.put(BASE_URL + '/api/v1/driver/devices',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"deviceId":"ios-installation-id","platform":"IOS","notificationsEnabled":true}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/devices');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X PUT '<base-url>/api/v1/driver/devices' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"deviceId":"ios-installation-id","platform":"IOS","notificationsEnabled":true}'

Request

Test URL JSON body

Response —

Run the request to see the response.

POST/api/v1/driver/trips/:id/feedback

Bearer token

Rate a rider with comment

Endpoint guide What to send, parse and expect

Why it exists

Stores one driver-to-rider rating after a completed trip.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

score is 1-5; comment is optional.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

201 creates feedback; 409 prevents duplicate ratings.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/:id/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"score":5,"comment":"Respectful rider"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"score":5,"comment":"Respectful rider"}''')
response = requests.post(BASE_URL + '/api/v1/driver/trips/:id/feedback',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"score":5,"comment":"Respectful rider"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/:id/feedback');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X POST '<base-url>/api/v1/driver/trips/:id/feedback' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{"score":5,"comment":"Respectful rider"}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/trips/:id/waiting-fee

Bearer token

Preview waiting fee after 3-minute grace period

Endpoint guide What to send, parse and expect

Why it exists

Returns the server-calculated waiting-time fee and no-show eligibility.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

No body. Fleet/admin owns the policy; money is kobo.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

200 returns waited minutes, billable minutes and fee.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/:id/waiting-fee', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/trips/:id/waiting-fee',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/:id/waiting-fee');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/trips/:id/waiting-fee' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

GET/api/v1/driver/trips/:id/location-replay

Bearer token

Replay own authorised trip location points

Endpoint guide What to send, parse and expect

Why it exists

Restores driver route points after reconnect.

Before you call

Use the method and authentication badge shown above. Replace every placeholder with a value returned by an earlier API call.

Request fields

Optional ?since=ISO timestamp.

What to parse

Check success first. On success, read data; on failure, render error.code and error.message.

Expected result

200 returns up to 2,000 ordered points.

Request structure and code samples Node.js · Python · PHP · cURL

Replace angle-bracket values with returned values. Use the raw access token only in the Authorization header.

Node.js

const response = await fetch(BASE_URL + '/api/v1/driver/trips/:id/location-replay', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({})
});
const result = await response.json();

Python

payload = json.loads(r'''{}''')
response = requests.get(BASE_URL + '/api/v1/driver/trips/:id/location-replay',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/driver/trips/:id/location-replay');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X GET '<base-url>/api/v1/driver/trips/:id/location-replay' \
+  -H 'Authorization: Bearer <access-token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <uuid>' \
+  --data '{}'

Request

Test URL JSON body

Response —

Run the request to see the response.

Errors and safetyResponses use JSON with a stable error code. Mutating requests receive an automatic idempotency key in the test console. Never paste production credentials here.