Admin API

Platform administration, operations, compliance and finance.

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.

Required availability order

POST /api/v1/driver/location with current GPS. Location freshness is checked by readiness.
PATCH /api/v1/driver/dispatch-preferences. Manual without a range: {"offerMode":"MANUAL","usePickupRadius":false}. Range-bound auto-accept: {"offerMode":"AUTO","usePickupRadius":true,"pickupRadiusKm":10}.
GET /api/v1/driver/readiness; show and resolve every blocker.
PATCH /api/v1/driver/status with {"status":"ONLINE"}.
Connect Socket.IO for the entire app session, then render offers and trip changes from events.

Auto-accept rule: it is disabled by default and never unbounded. The driver sets the pickup range themselves. Enabling AUTO without an enabled range returns 409 AUTO_ACCEPT_REQUIRES_PICKUP_RANGE. To turn the range off, switch to MANUAL in the same update. The server, not the app timer, decides eligibility and acceptance.

Live activity: connect Socket.IO with auth.token = accessToken. In MANUAL mode, treat driver:trip_offer as an interrupting offer, fetch GET /driver/offers for display/recovery details, and count down to expiresAt; then call POST /driver/offers/:id/respond. In AUTO mode, render trip:state_updated as the confirmation that the range-qualified offer was assigned. Handle driver:trip_offer_expired, driver:trip_offer_retracted and message:received. After every reconnect, refetch active offers, active trips and messages.

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 NGN 2,465; divide by 100 for display. JSON body editors are automatically pretty-printed when valid JSON is entered.

GET/api/v1/admin/operational-documents

Bearer token

List vehicle documents awaiting Admin review

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/admin/operational-documents', {
  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/admin/operational-documents',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/operational-documents');
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/admin/operational-documents' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": [
    {
      "id": "8af7456d-32d1-439d-9d01-070e959babf9",
      "type": "VEHICLE_INSURANCE",
      "status": "PENDING_REVIEW",
      "fleet": {
        "id": "FLT_b1fe6573-3a25-4d13-b41e-55143176d849",
        "name": "Cruz Fleet PH"
      }
    }
  ],
  "error": null
}

PATCH/api/v1/admin/operational-documents/:id/review

Bearer token

Approve or reject a vehicle document

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/admin/operational-documents/:id/review', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"decision":"APPROVED","note":"Verified"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"decision":"APPROVED","note":"Verified"}''')
response = requests.patch(BASE_URL + '/api/v1/admin/operational-documents/:id/review',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"decision":"APPROVED","note":"Verified"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/operational-documents/:id/review');
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/admin/operational-documents/:id/review' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"decision":"APPROVED","note":"Verified"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "8af7456d-32d1-439d-9d01-070e959babf9",
    "status": "APPROVED",
    "note": "Verified"
  },
  "error": null
}

GET/api/v1/admin/pricing

Bearer token

Read fare versions, waiting policy and operating/fare zones

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/admin/pricing', {
  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/admin/pricing',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/pricing');
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/admin/pricing' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<resource-id>",
    "status": "OK"
  },
  "error": null
}

PUT/api/v1/admin/pricing/fleets/:id

Bearer token

Publish the live fare and waiting policy (super admin only)

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/admin/pricing/fleets/:id', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"baseFareMinor":40000,"perKmMinor":9000,"perMinuteMinor":900,"minimumFareMinor":40000,"currency":"NGN","surgeRules":{"multiplierBps":10000},"waiting":{"enabled":true,"graceMinutes":3,"perMinuteMinor":900,"noShowAfterMinutes":10},"reason":"Approved fare publication","confirmed":true,"idempotencyKey":"<uuid>"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"baseFareMinor":40000,"perKmMinor":9000,"perMinuteMinor":900,"minimumFareMinor":40000,"currency":"NGN","surgeRules":{"multiplierBps":10000},"waiting":{"enabled":true,"graceMinutes":3,"perMinuteMinor":900,"noShowAfterMinutes":10},"reason":"Approved fare publication","confirmed":true,"idempotencyKey":"<uuid>"}''')
response = requests.put(BASE_URL + '/api/v1/admin/pricing/fleets/:id',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"baseFareMinor":40000,"perKmMinor":9000,"perMinuteMinor":900,"minimumFareMinor":40000,"currency":"NGN","surgeRules":{"multiplierBps":10000},"waiting":{"enabled":true,"graceMinutes":3,"perMinuteMinor":900,"noShowAfterMinutes":10},"reason":"Approved fare publication","confirmed":true,"idempotencyKey":"<uuid>"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/pricing/fleets/:id');
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/admin/pricing/fleets/:id' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"baseFareMinor":40000,"perKmMinor":9000,"perMinuteMinor":900,"minimumFareMinor":40000,"currency":"NGN","surgeRules":{"multiplierBps":10000},"waiting":{"enabled":true,"graceMinutes":3,"perMinuteMinor":900,"noShowAfterMinutes":10},"reason":"Approved fare publication","confirmed":true,"idempotencyKey":"<uuid>"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "status": "OK"
  },
  "error": null
}

POST/api/v1/admin/geofences

Bearer token

Create a drawn service area or nested fare zone

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/admin/geofences', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"fleetId":"<uuid>","name":"Lagos airport","kind":"AIRPORT","geometry":{"type":"Polygon","coordinates":[[[3.30,6.55],[3.35,6.55],[3.35,6.60],[3.30,6.55]]]},"modifierType":"FIXED","surchargeMinor":50000,"multiplierBps":10000,"appliesTo":"PICKUP_OR_DROPOFF","stateCode":"LA","active":true,"reason":"Approved airport fee","confirmed":true,"idempotencyKey":"<uuid>"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"fleetId":"<uuid>","name":"Lagos airport","kind":"AIRPORT","geometry":{"type":"Polygon","coordinates":[[[3.30,6.55],[3.35,6.55],[3.35,6.60],[3.30,6.55]]]},"modifierType":"FIXED","surchargeMinor":50000,"multiplierBps":10000,"appliesTo":"PICKUP_OR_DROPOFF","stateCode":"LA","active":true,"reason":"Approved airport fee","confirmed":true,"idempotencyKey":"<uuid>"}''')
response = requests.post(BASE_URL + '/api/v1/admin/geofences',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"fleetId":"<uuid>","name":"Lagos airport","kind":"AIRPORT","geometry":{"type":"Polygon","coordinates":[[[3.30,6.55],[3.35,6.55],[3.35,6.60],[3.30,6.55]]]},"modifierType":"FIXED","surchargeMinor":50000,"multiplierBps":10000,"appliesTo":"PICKUP_OR_DROPOFF","stateCode":"LA","active":true,"reason":"Approved airport fee","confirmed":true,"idempotencyKey":"<uuid>"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/geofences');
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/admin/geofences' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"fleetId":"<uuid>","name":"Lagos airport","kind":"AIRPORT","geometry":{"type":"Polygon","coordinates":[[[3.30,6.55],[3.35,6.55],[3.35,6.60],[3.30,6.55]]]},"modifierType":"FIXED","surchargeMinor":50000,"multiplierBps":10000,"appliesTo":"PICKUP_OR_DROPOFF","stateCode":"LA","active":true,"reason":"Approved airport fee","confirmed":true,"idempotencyKey":"<uuid>"}'

Request

Test URL JSON body

Response

HTTP 201 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<created-id>",
    "status": "CREATED"
  },
  "error": null
}

PATCH/api/v1/admin/geofences/:id

Bearer token

Edit and version an operating or fare zone

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/admin/geofences/:id', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"multiplierBps":12500,"modifierType":"MULTIPLIER","reason":"Approved zone adjustment","confirmed":true,"idempotencyKey":"<uuid>"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"multiplierBps":12500,"modifierType":"MULTIPLIER","reason":"Approved zone adjustment","confirmed":true,"idempotencyKey":"<uuid>"}''')
response = requests.patch(BASE_URL + '/api/v1/admin/geofences/:id',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"multiplierBps":12500,"modifierType":"MULTIPLIER","reason":"Approved zone adjustment","confirmed":true,"idempotencyKey":"<uuid>"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/geofences/:id');
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/admin/geofences/:id' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"multiplierBps":12500,"modifierType":"MULTIPLIER","reason":"Approved zone adjustment","confirmed":true,"idempotencyKey":"<uuid>"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<updated-id>",
    "status": "UPDATED"
  },
  "error": null
}

DELETE/api/v1/admin/geofences/:id

Bearer token

Deactivate a zone without deleting its history

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/admin/geofences/:id', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"reason":"Zone retired","confirmed":true,"idempotencyKey":"<uuid>"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"reason":"Zone retired","confirmed":true,"idempotencyKey":"<uuid>"}''')
response = requests.delete(BASE_URL + '/api/v1/admin/geofences/:id',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"reason":"Zone retired","confirmed":true,"idempotencyKey":"<uuid>"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/geofences/:id');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Idempotency-Key: <uuid>'],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
]);

cURL

curl -X DELETE '<base-url>/api/v1/admin/geofences/:id' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"reason":"Zone retired","confirmed":true,"idempotencyKey":"<uuid>"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<deleted-id>",
    "deleted": true
  },
  "error": null
}

GET/api/v1/admin/geocoding/search?q=Lagos

Bearer token

Search the configured Nigeria geocoder for the Leaflet editor

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/admin/geocoding/search?q=Lagos', {
  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/admin/geocoding/search?q=Lagos',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/geocoding/search?q=Lagos');
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/admin/geocoding/search?q=Lagos' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<resource-id>",
    "status": "OK"
  },
  "error": null
}

GET/api/v1/admin/users

Bearer token

Search/list platform accounts

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/admin/users', {
  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/admin/users',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/users');
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/admin/users' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<resource-id>",
    "status": "OK"
  },
  "error": null
}

PATCH/api/v1/admin/users/:id/access

Bearer token

Reinstate, suspend or permanently deactivate an account

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/admin/users/:id/access', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"status":"SUSPENDED","reason":"Policy review"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"status":"SUSPENDED","reason":"Policy review"}''')
response = requests.patch(BASE_URL + '/api/v1/admin/users/:id/access',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"status":"SUSPENDED","reason":"Policy review"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/users/:id/access');
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/admin/users/:id/access' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"status":"SUSPENDED","reason":"Policy review"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<updated-id>",
    "status": "UPDATED"
  },
  "error": null
}

PATCH/api/v1/admin/drivers/:id/status

Bearer token

Suspend/reinstate a driver with notification

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/admin/drivers/:id/status', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"status":"SUSPENDED","reason":"Compliance review"})
});
const result = await response.json();

Python

payload = json.loads(r'''{"status":"SUSPENDED","reason":"Compliance review"}''')
response = requests.patch(BASE_URL + '/api/v1/admin/drivers/:id/status',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"status":"SUSPENDED","reason":"Compliance review"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/drivers/:id/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/admin/drivers/:id/status' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"status":"SUSPENDED","reason":"Compliance review"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<updated-id>",
    "status": "UPDATED"
  },
  "error": null
}

POST/api/v1/admin/notifications

Bearer token

Send rider, driver or fleet-driver notification

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/admin/notifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"recipientKind":"DRIVER","driverId":"DRV_<uuid>","type":"ADMIN_MESSAGE","title":"Account update","body":"Please contact support."})
});
const result = await response.json();

Python

payload = json.loads(r'''{"recipientKind":"DRIVER","driverId":"DRV_<uuid>","type":"ADMIN_MESSAGE","title":"Account update","body":"Please contact support."}''')
response = requests.post(BASE_URL + '/api/v1/admin/notifications',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"recipientKind":"DRIVER","driverId":"DRV_<uuid>","type":"ADMIN_MESSAGE","title":"Account update","body":"Please contact support."}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/notifications');
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/admin/notifications' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"recipientKind":"DRIVER","driverId":"DRV_<uuid>","type":"ADMIN_MESSAGE","title":"Account update","body":"Please contact support."}'

Request

Test URL JSON body

Response

HTTP 201 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "<created-id>",
    "status": "CREATED"
  },
  "error": null
}

GET/api/v1/admin/dashboard

Bearer token

Platform dashboard

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/admin/dashboard', {
  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/admin/dashboard',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/dashboard');
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/admin/dashboard' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "fleets": 12,
    "activeDrivers": 48,
    "openIncidents": 3,
    "pendingDocuments": 7
  },
  "error": null
}

GET/api/v1/admin/fleets

Bearer token

Fleet list

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/admin/fleets', {
  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/admin/fleets',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/fleets');
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/admin/fleets' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": [
    {
      "id": "FLT_b1fe6573-3a25-4d13-b41e-55143176d849",
      "name": "Cruz Fleet PH",
      "status": "ACTIVE"
    }
  ],
  "error": null
}

PATCH/api/v1/admin/fleets/:id/status

Bearer token

Change fleet status

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/admin/fleets/:id/status', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"status":"ACTIVE"})
});
const result = await response.json();

Python

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

PHP

$payload = <<<'JSON'
{"status":"ACTIVE"}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/fleets/:id/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/admin/fleets/:id/status' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"status":"ACTIVE"}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "b1fe6573-3a25-4d13-b41e-55143176d849",
    "status": "ACTIVE"
  },
  "error": null
}

PATCH/api/v1/admin/fleets/:id/remittance-policy

Bearer token

Set a fleet cash-remittance threshold and online enforcement

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/admin/fleets/:id/remittance-policy', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <access-token>',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({"enabled":true,"thresholdMinor":500000,"blockOnline":true})
});
const result = await response.json();

Python

payload = json.loads(r'''{"enabled":true,"thresholdMinor":500000,"blockOnline":true}''')
response = requests.patch(BASE_URL + '/api/v1/admin/fleets/:id/remittance-policy',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{"enabled":true,"thresholdMinor":500000,"blockOnline":true}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/fleets/:id/remittance-policy');
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/admin/fleets/:id/remittance-policy' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{"enabled":true,"thresholdMinor":500000,"blockOnline":true}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": {
    "id": "b1fe6573-3a25-4d13-b41e-55143176d849",
    "remittancePolicy": {
      "enabled": true,
      "thresholdMinor": 500000,
      "blockOnline": true
    }
  },
  "error": null
}

GET/api/v1/admin/incidents

Bearer token

Safety incidents

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/admin/incidents', {
  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/admin/incidents',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/incidents');
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/admin/incidents' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": [
    {
      "id": "INC_4a57456d-32d1-439d-9d01-070e959babf9",
      "status": "OPEN",
      "severity": "CRITICAL",
      "type": "SOS"
    }
  ],
  "error": null
}

GET/api/v1/admin/audit

Bearer token

Audit events

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/admin/audit', {
  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/admin/audit',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json=payload)
result = response.json()

PHP

$payload = <<<'JSON'
{}
JSON;
$ch = curl_init($baseUrl . '/api/v1/admin/audit');
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/admin/audit' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid>' \
  --data '{}'

Request

Test URL JSON body

Response

HTTP 200 · FIXED TEST RESPONSE

{
  "success": true,
  "data": [
    {
      "id": "AUD_7c67456d-32d1-439d-9d01-070e959babf9",
      "action": "DRIVER_CREATED",
      "createdAt": "2026-08-28T18:00:00.000Z"
    }
  ],
  "error": null
}

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.