Integration API

The API is JSON over HTTPS, under /api/v1 on the platform’s address (the APP_URL your IT team set, for example https://academy.example.com). There are four endpoints:

The examples use two shell variables:

export BASE="https://academy.example.com"
export KEY="<your INTEGRATION_API_KEY>"

1. Rider system

   Sends new and changed riders to POST /riders.

2. Assignment rules

   Onboarding and auto-assign paths are given to matching riders.

3. Ops systems

   Send flags to POST /flags. Corrective paths are assigned, links sent.

4. Riders train

   On their phone, in their language.

5. Analytics

   Reads passed courses from GET /completions.

• Riders: send riders when they join and whenever their market, vehicle, language or status changes. New riders with status onboarding get the onboarding path.
• Flags: send a flag when a performance issue is confirmed. The rider must already exist.
• Assignments: for campaigns, for example a new policy for every active rider in one market.
• Completions: poll regularly (for example hourly) and store the records in your data warehouse.

The training team can do the same by hand in the admin panel: CSV import for riders (useful for bucket files), flags and Assign now on the rider and path pages, and CSV exports.

Every request must carry the integration key that IT set on the server in INTEGRATION_API_KEY, in one of these headers:

x-api-key: <INTEGRATION_API_KEY>
Authorization: Bearer <INTEGRATION_API_KEY>

• If both headers are sent, x-api-key is used.
• The key must match exactly (it is case-sensitive).
• There is one key for all integrations. To rotate it, IT changes the variable and restarts the app; the old key stops working at once.

• Send JSON request bodies with Content-Type: application/json. Responses are JSON.
• Every error has the same JSON body: {"error":"message","code":"invalid_request"}. error is a readable message; code is stable for your code to check: invalid_request, unauthorized, not_found, conflict, internal_error or api_disabled. The riders endpoint also returns per-row errors (see below).
• Rider IDs are rider IDs sent as strings: "300001", not 300001.
• Don’t send null for optional fields: leave the field out. Unknown fields are ignored.
• Timestamps are ISO 8601 in UTC, for example 2026-09-17T08:30:12.345Z.
• A write that clashes with a change made at the same moment returns 409 with code conflict: retry it. An unexpected server error returns 500 with code internal_error: retry later; IT can check the logs.

POST/api/v1/riders

Creates new riders and updates existing ones, matched on riderId. After saving, the automatic learning path rules (“Auto-assign to every matching rider” and “Riders in onboarding status”) run for all riders.

Each rider object:

• Optional fields that you leave out, or send as an empty string, keep their current value. There is no way to clear a field.
• If the same riderId appears twice in one request, the last one wins.
• For large files, send batches of up to 5,000 riders one after the other. Each call runs the assignment rules.

curl -X POST "$BASE/api/v1/riders" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "riders": [
      {
        "riderId": "300001",
        "name": "Ali Hassan",
        "market": "KW",
        "city": "Hawalli",
        "vehicleType": "motorbike",
        "nationality": "Egyptian",
        "language": "ar",
        "status": "onboarding",
        "phone": "+96550000001"
      },
      { "riderId": "300002", "name": "Imran Ali", "market": "XX" }
    ]
  }'

Response, status 200 (one rider saved, one rejected):

{
  "inserted": 1,
  "updated": 0,
  "enrollmentsCreated": 1,
  "errors": [
    { "index": 1, "error": "market must be one of AE, KW, QA, BH, OM, JO, EG, IQ (or the market name, e.g. Qatar)" }
  ]
}

Examples of row errors:

POST/api/v1/flags

Records a performance flag for an existing rider and assigns matching corrective training straight away.

What happens:

• The flag is saved with source “api” and shows on the rider page as “via api”.
• Every active learning path set to “When a rider gets a flag” with this flag type is assigned, if the rider matches the path’s market, vehicle and nationality filters, isn’t inactive, and doesn’t already have that path open.
• With notify: true, the link is sent on WhatsApp when the Cloud API is connected and the rider has a phone number. Otherwise it is logged for the training team to share.

curl -X POST "$BASE/api/v1/flags" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"riderId":"300001","type":"customer_complaint","note":"Order left at the wrong door","notify":true}'

Response, status 200:

{
  "flagId": "5b0c1f3e-8d2a-4c7e-9a41-2f6d8e3b7c10",
  "enrollmentsCreated": 1,
  "notification": "logged"
}

POST/api/v1/assignments

Assigns a learning path to riders chosen by rider ID, by filters, or both. It works like Assign now in the admin panel.

• Give riderIds, at least one filter, or both.
• All criteria combine: a rider must match every filter and be in riderIds if given. Within one array, any value matches.
• Filter values are matched exactly, so use upper-case market codes and lower-case vehicle types and statuses.
• Riders with status inactive are never assigned. Unknown rider IDs are ignored.
• Riders who already have the path open are skipped. Riders who finished it before are assigned again; courses they already passed count, so the assignment can complete straight away (see How assignments are completed).
• The path’s own rule, filters and Active setting are ignored. The deadline is now plus the path’s days to complete.
• No message is sent to riders. The rider page shows the assignment with Why “api”.
• The city filter of the admin panel isn’t available in the API.

# Every active rider in Egypt and Jordan
curl -X POST "$BASE/api/v1/assignments" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"pathId":"8f14e45f-ceea-467a-9575-1a2b3c4d5e6f","markets":["EG","JO"],"statuses":["active"]}'

# Specific riders
curl -X POST "$BASE/api/v1/assignments" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"pathId":"8f14e45f-ceea-467a-9575-1a2b3c4d5e6f","riderIds":["300001","300002","300003"]}'

Response, status 200:

{ "enrollmentsCreated": 1250 }

GET/api/v1/completions?cursor=<nextCursor>&limit=<1-5000>

Returns passed course records, one per rider per course, ordered by completion time, oldest first. Use it to copy completions into your analytics.

curl -G "$BASE/api/v1/completions" \
  -H "x-api-key: $KEY" \
  --data-urlencode "since=2026-09-01T00:00:00Z" \
  --data-urlencode "limit=1000"

Response, status 200:

{
  "data": [
    {
      "riderId": "300001",
      "market": "KW",
      "courseId": "0b6c7d9e-3f1a-4b2c-8d5e-6f7a8b9c0d1e",
      "course": "Food safety on the road",
      "language": "ar",
      "startedAt": "2026-09-02T10:14:03.120Z",
      "completedAt": "2026-09-02T10:21:47.908Z",
      "score": 80,
      "attempts": 2,
      "timeSpentSeconds": 402,
      "proofCode": "3F9A1C0B"
    }
  ],
  "next": null,
  "nextCursor": null
}

• First request: since (or nothing, for everything). Then, while nextCursor isn’t null, call again with cursor=nextCursor.
• When a page comes back with nextCursor null, you have everything for now. To pick up new completions later, start again with since set to the completedAt of the last record you stored (you may receive that record again), then page with cursor. Don’t page with since=next: it can skip records that share a completion time.
• Paging with cursor is stable: no record is skipped or repeated between pages, even when several records share the same completion time. Use proofCode (or riderId + courseId) as the key when storing records, so reading a record twice is harmless.
• The feed covers every market and every rider status. It doesn’t include riders who opened a course but haven’t passed; use the admin panel export for those.

page=$(curl -sfG "$BASE/api/v1/completions" -H "x-api-key: $KEY" \
  --data-urlencode "since=2026-09-01T00:00:00Z" --data-urlencode "limit=1000") || exit 1
while :; do
  echo "$page" | jq -c '.data[]' >> completions.jsonl
  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
  page=$(curl -sfG "$BASE/api/v1/completions" -H "x-api-key: $KEY" \
    --data-urlencode "cursor=$cursor" --data-urlencode "limit=1000") || exit 1
done

Every error body is {"error":"message","code":"..."}.

• Use a test rider ID that can’t clash with real riders. Test riders count in the dashboard and reports, so keep them few and easy to recognise.
• Create the rider with POST /riders, then check it in the admin panel under Riders.
• Send a flag with notify: false and check the rider page shows the flag “via api” and the assigned path.
• Pass a course as the test rider in the rider app, then read it back with GET /completions.
• Set the test rider’s status to inactive when you’re done. There’s no delete endpoint.