Drivers

11 API calls in this section.

Endpoints for managing drivers, including multi-vehicle assignments, wallet/accounting views, creation, updates, deletion, and location tracking.

List Drivers

Delivery & Last-Mile / Drivers

GET/delivery/drivers

Returns paginated drivers with a live workload object for assignment pickers. workload.capacity contains total (primary vehicle capacity_unit, or null), filled (authoritative drivers.used_capacity_unit), and available (max(total - filled, 0), or null when total is unknown). workload.orders contains assigned (pending, assigned, or accepted assignments), in_progress (en_route_to_pickup, picked_up, or en_route_to_delivery assignments), and active (all distinct non-terminal assigned deliveries). Order counts exclude deleted, delivered, failed, cancelled, and returned deliveries even when a custody assignment remains for return handoff. Workload is informational only and does not change driver eligibility, capacity enforcement, zone rules, or assignment behavior. Frontend integration: fetch this endpoint fresh whenever an assignment driver picker opens, render the workload summary from the returned values, and continue using drivers[].id as the assignment driver_id.

Get a paginated list of drivers with optional filtering. Requires view:tenant permission or system admin privileges.

• Type: JWT Bearer Token

• Permissions: Requires view:tenant or user must be a system admin.

Responses

Returns a list of drivers.

Response Fields

• success (boolean): Indicates if the request was successful.

• message (string): Localized success message.

• drivers (array): List of driver objects.

  • id (string, UUID): Driver's unique ID.

  • tenant_id (string, UUID): Tenant ID.

  • status (string): Current status of the driver.

  • created_at (string, ISO8601 DateTime): Timestamp of creation.

  • license_number (string): Driver's license number.

  • vehicle (object): Assigned vehicle details.

    • id (string, UUID): Vehicle ID.

    • name (string): Vehicle name.

  • zones (array of objects): Assigned delivery zones.

    • id (string, UUID): Zone ID.

    • name (string): Zone name.

  • user (object): Associated user details.

    • id (string, UUID): User ID.

    • full_name (string): User's full name.

• page (integer): Current page number.

• limit (integer): Number of items per page.

• total (integer): Total number of drivers found.

If tenant_id is missing and not available in context.

Standard unauthorized response if token is missing or invalid.

User does not have the required permissions.

If there's an issue with the database query or an unexpected server error.

Query parameters

Parameter	Type	Description
pageOptional	string	(integer, optional, default: 1): Page number for pagination. Example: 1 (integer, optional, default: 1): Page number for pagination. Example: 1 Example: 1
limitOptional	string	(integer, optional, default: 10): Number of items per page. Example: 10 (integer, optional, default: 10): Number of items per page. Example: 10 Example: 10
searchOptional	string	Search by driver full name, phone, email, or license number (string, optional): Search term to filter by driver's full name or license number. Example: John Search by driver full name, phone, email, or license number (string, optional): Search term to filter by driver's full name or license number. Example: John
statusOptional	string	Filter by driver status (active, inactive, on_break, etc.) (string, optional): Filter by driver status (e.g., 'active', 'inactive', 'on_break'). Example: active Filter by driver status (active, inactive, on_break, etc.) (string, optional): Filter by driver status (e.g., 'active', 'inactive', 'on_break'). Example: active
vehicle_idOptional	string	(string, UUID, optional): Filter by vehicle ID. Example: a1b2c3d4-e5f6-7890-1234-567890abcdef (string, UUID, optional): Filter by vehicle ID. Example: a1b2c3d4-e5f6-7890-1234-567890abcdef
zone_idOptional	string	(string, UUID, optional): Filter by delivery zone ID. Example: b2c3d4e5-f6a7-8901-2345-67890abcdef0 (string, UUID, optional): Filter by delivery zone ID. Example: b2c3d4e5-f6a7-8901-2345-67890abcdef0
column_filters	string	JSON string for column filters. Supported keys: status, is_online, created_at, vehicle_id, zone_id, license_number JSON string for column filters. Supported keys: status, is_online, created_at, vehicle_id, zone_id, license_number Example: {"status":"active","is_online":true,"created_at":{"from":"2025-01-01","to":"2025-12-31"},"vehicle_id":"uuid1,uuid2","zone_id":"uuid3,uuid4","license_number":"DL123"}
sort_by	string	Sort column. Supported values: created_at, license_number Sort column. Supported values: created_at, license_number Example: created_at
sort_order	string	Sort order. Supported values: asc, desc Sort order. Supported values: asc, desc Example: desc
tenant_idOptional	string	Tenant ID (optional if in auth token) (string, UUID, optional): Tenant ID. If not provided, it's taken from the authenticated user's context. Example: c3d4e5f6-a7b8-9012-3456-7890abcdef01 Tenant ID (optional if in auth token) (string, UUID, optional): Tenant ID. If not provided, it's taken from the authenticated user's context. Example: c3d4e5f6-a7b8-9012-3456-7890abcdef01
languageOptional	string	(string, optional, default: 'en'): Preferred language for response messages. Example: en (string, optional, default: 'en'): Preferred language for response messages. Example: en Example: en

Headers

Parameter	Type	Description
Authorization	string	Bearer {{access_token}} Bearer {{access_token}} Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/drivers?page=1&limit=10&search=&status=&vehicle_id=&zone_id=&column_filters=%7B%22status%22%3A%22active%22%2C%22is_online%22%3Atrue%2C%22created_at%22%3A%7B%22from%22%3A%222025-01-01%22%2C%22to%22%3A%222025-12-31%22%7D%2C%22vehicle_id%22%3A%22uuid1%2Cuuid2%22%2C%22zone_id%22%3A%22uuid3%2Cuuid4%22%2C%22license_number%22%3A%22DL123%22%7D&sort_by=created_at&sort_order=desc&tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Live Driver Workload200 · Success Response200 · Success (200 OK)400 · Error (400 Bad Request - Invalid Request)401 · Standard unauthorized response if token is missing or invalid.403 · Error (403 Forbidden - Insufficient Permissions)500 · Error (500 Internal Server Error)

200OK

Response body

json

1{2  "success": true,3  "message": "Drivers retrieved successfully",4  "drivers": [5    {6      "id": "driver-uuid-123",7      "users": {8        "full_name": "Alan Test Driver",9        "phone": "+9647500000000"10      },11      "operation_status": "available",12      "vehicle": {13        "id": "vehicle-uuid-789",14        "capacity_unit": 10015      },16      "workload": {17        "capacity": {18          "total": 100,19          "filled": 76,20          "available": 2421        },22        "orders": {23          "assigned": 3,24          "in_progress": 1,25          "active": 426        }27      }28    }29  ],30  "page": 1,31  "limit": 10,32  "total": 133}

Get Driver

Delivery & Last-Mile / Drivers

GET/delivery/drivers/:driverId

Get details for a specific driver. Requires view:tenant or manage:operations:tenant permission or system admin privileges.

• Type: JWT Bearer Token

• Permissions: Requires view:tenant, manage:operations:tenant, or user must be a system admin.

Responses

Returns details of the specified driver.

Response Fields

• success (boolean): Indicates if the request was successful.

• message (string): Localized success message.

• driver (object): Driver details.

  • id (string, UUID): Driver's unique ID.

  • user (object): Associated user details.

    • id (string, UUID): User ID.

    • full_name (string): User's full name.

  • vehicle (object): Assigned vehicle details.

    • id (string, UUID): Vehicle ID.

    • name (string): Vehicle name.

  • license_number (string): Driver's license number.

  • zones (array of objects): Assigned delivery zones.

    • id (string, UUID): Zone ID.

    • name (string): Zone name.

  • preferred_zones (array of objects): Preferred delivery zones for auto-assignment priority. Contains zone details with id, name, and code. Empty array if no preferred zones are set.

    • id (string, UUID): Zone ID.

    • name (string): Zone name.

    • code (string): Zone code.

  • driver_details (object): Additional JSON details about the driver.

  • status (string): Current status of the driver.

If tenant_id is missing and not available in context.

Standard unauthorized response.

User does not have the required permissions.

If the driver with the specified ID does not exist or does not belong to the tenant.

If there's an issue with the database query or an unexpected server error.

Path parameters

Parameter	Type	Description
driverIdRequired	string	ID of the driver to retrieve (string, UUID, required): The unique identifier of the driver to retrieve. Example: driver-uuid-123 ID of the driver to retrieve (string, UUID, required): The unique identifier of the driver to retrieve. Example: driver-uuid-123 Example: uuid

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) (string, UUID, optional): Tenant ID. If not provided, it's taken from the authenticated user's context. Example: c3d4e5f6-a7b8-9012-3456-7890abcdef01 Tenant ID (optional if in auth token) (string, UUID, optional): Tenant ID. If not provided, it's taken from the authenticated user's context. Example: c3d4e5f6-a7b8-9012-3456-7890abcdef01
languageOptional	string	(string, optional, default: 'en'): Preferred language for response messages. Example: en (string, optional, default: 'en'): Preferred language for response messages. Example: en Example: en

Headers

Parameter	Type	Description
Authorization	string	Bearer {{access_token}} Bearer {{access_token}} Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success Response404 · Error - Driver Not Found200 · Success (200 OK)400 · Error (400 Bad Request - Invalid Request)401 · Standard unauthorized response.403 · Error (403 Forbidden - Insufficient Permissions)500 · Error (500 Internal Server Error)

200OK

Response body

json

1{2  "success": true,3  "message": "Driver retrieved successfully",4  "driver": {5    "driver_id": "driver-uuid-123",6    "license_number": "DL12345678",7    "status": "active",8    "driver_details": {},9    "documents": {10      "avatar": [11        "https://example.com/avatar.jpg"12      ],13      "identity_card_photos": [14        "https://example.com/id-front.jpg",15        "https://example.com/id-back.jpg"16      ],17      "driving_licence_photos": [18        "https://example.com/licence-front.jpg"19      ],20      "vehicle_photos": [21        "https://example.com/car-front.jpg",22        "https://example.com/car-side.jpg"23      ]24    },25    "is_online": true,26    "all_zones": false,27    "used_capacity_unit": 25,28    "current_location": {29      "latitude": 37.7749,30      "longitude": -122.4194,31      "last_update": "2023-08-01T15:30:00Z"32    },33    "user_id": "user-uuid-def",34    "email": "john.driver@example.com",35    "first_name": "John",36    "last_name": "Driver",37    "full_name": "John Driver",38    "phone": "+1234567890",39    "avatar_url": "https://example.com/avatar.jpg",40    "profile_data": {},41    "user_status": "active",42    "vehicle": {43      "id": "vehicle-uuid-789",44      "name": "Van 101",45      "code": "VAN001",46      "image_url": "https://example.com/van.jpg",47      "capacity_unit": 5048    },49    "delivery_zones": [50      {51        "id": "zone-uuid-abc",52        "name": "Downtown",53        "code": "DT"54      }55    ],56    "preferred_zones": [],57    "created_at": "2023-07-01T10:00:00Z",58    "updated_at": "2023-08-01T15:30:00Z"59  }60}

Create Driver

Delivery & Last-Mile / Drivers

POST/delivery/drivers

Create a new driver. Requires manage:users:tenant permission.

Validation Rules

• If all_zones is true, zone_ids must not be provided

• If all_zones is false, zone_ids must be provided with at least one zone

• preferred_zone_ids must be a subset of zone_ids when all_zones is false

• preferred_zone_ids zones must exist in the delivery_zones table

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
user_idRequired	string	(string, UUID, required): User ID to assign as driver (string, UUID, required): User ID to assign as driver
vehicle_ids	array<string>	—
primary_vehicle_id	string	—
license_numberOptional	string	(string, optional): Driver's license number (string, optional): Driver's license number
all_zonesOptional	boolean	(boolean, optional, default: false): If true, driver can operate in all zones. If false, driver can only operate in zones specified in zone_ids (boolean, optional, default: false): If true, driver can operate in all zones. If false, driver can only operate in zones specified in zone_ids
zone_ids	array<string>	(array of UUIDs, required if all_zones is false): Array of delivery zone IDs the driver can operate in. Cannot be provided if all_zones is true (array of UUIDs, required if all_zones is false): Array of delivery zone IDs the driver can operate in. Cannot be provided if all_zones is true
preferred_zone_idsOptional	array<string>	(array of UUIDs, optional): Array of preferred delivery zone IDs for auto-assignment priority. Must be subset of zone_ids if all_zones is false. Empty array or omitted means no zone preference (array of UUIDs, optional): Array of preferred delivery zone IDs for auto-assignment priority. Must be subset of zone_ids if all_zones is false. Empty array or omitted means no zone preference
statusOptional	string	(string, optional, default: "active"): Driver status (string, optional, default: "active"): Driver status
identity_card_photos	array<string>	—
driving_licence_photos	array<string>	—
vehicle_photos	array<string>	—
national_idOptional	string	(string, optional): National ID (persisted in drivers.national_id) (string, optional): National ID (persisted in drivers.national_id)

Show 14 more body fields

Additional body parameters

Parameter	Type	Description
bank_infoOptional	object	(object, optional): Bank fields — bank_name, account_name, account_number, iban, swift_code, branch_name (persisted in drivers.bank_info JSONB) (object, optional): Bank fields — bank_name, account_name, account_number, iban, swift_code, branch_name (persisted in drivers.bank_info JSONB)
bank_info.bank_name	string	—
bank_info.account_name	string	—
bank_info.account_number	string	—
bank_info.iban	string	—
bank_info.swift_code	string	—
bank_info.branch_name	string	—
addressOptional	object	(object or string, optional): Structured address JSON (persisted in drivers.address); string values are normalized to { line1: "..." } (object or string, optional): Structured address JSON (persisted in drivers.address); string values are normalized to { line1: "..." }
address.line1	string	—
address.city	string	—
address.country	string	—
driver_detailsOptional	object	(object, optional): Additional driver-specific information (legacy bag; bank_info, national_id, address are stripped here and stored in DB columns when provided) (object, optional): Additional driver-specific information (legacy bag; bank_info, national_id, address are stripped here and stored in DB columns when provided)
driver_details.rating	null	—
vehicle_idRequired	string	(string, UUID, required): Vehicle ID to assign to driver (string, UUID, required): Vehicle ID to assign to driver

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/drivers?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "user_id": "uuid",6  "vehicle_ids": [7    "vehicle-uuid-1",8    "vehicle-uuid-2"9  ],10  "primary_vehicle_id": "vehicle-uuid-1",11  "license_number": "DL12345678",12  "all_zones": false,13  "zone_ids": [14    "uuid1",15    "uuid2"16  ],17  "preferred_zone_ids": [18    "uuid1"19  ],20  "status": "active",21  "identity_card_photos": [22    "https://example.com/id-front.jpg",23    "https://example.com/id-back.jpg"24  ],25  "driving_licence_photos": [26    "https://example.com/licence-front.jpg"27  ],28  "vehicle_photos": [29    "https://example.com/car-front.jpg",30    "https://example.com/car-side.jpg"31  ],32  "national_id": "1234567890",33  "bank_info": {34    "bank_name": "Example Bank",35    "account_name": "John Driver",36    "account_number": "000111",37    "iban": "IQ00XXXX",38    "swift_code": "EXAMIQB0",39    "branch_name": "Main"40  },41  "address": {42    "line1": "Street 1",43    "city": "Baghdad",44    "country": "IQ"45  },46  "driver_details": {47    "rating": null48  }49}'

Response examples

201Created

Response body

json

1{2  "success": true,3  "message": "Driver created successfully",4  "id": "uuid"5}

Create Driver (Wizard)

Delivery & Last-Mile / Drivers

POST/delivery/drivers/wizard

Create driver wizard. Always creates user from user object. Use vehicle_ids + primary_vehicle_id for existing vehicles, or use inline vehicle to create a new primary vehicle.

Optional profile fields (stored on drivers): bank_info (object), national_id (string), address (object or string). Same semantics as create driver.

Frontend integration

on HTTP 409, display the response message. Phone conflicts return This phone number is already registered to another account; email conflicts return This email is already registered to another account.

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
user	object	—
user.email	string	—
user.phone	string	—
user.password	string	—
user.first_name	string	—
user.last_name	string	—
vehicle_ids	array<string>	—
primary_vehicle_id	string	—
license_number	string	—
all_zones	boolean	—
zone_ids	array<string>	—
preferred_zone_ids	array<string>	—

Show 11 more body fields

Additional body parameters

Parameter	Type	Description
status	string	—
national_id	string	—
bank_info	object	—
bank_info.bank_name	string	—
bank_info.iban	string	—
address	object	—
address.line1	string	—
address.city	string	—
identity_card_photos	array<string>	—
driving_licence_photos	array<string>	—
vehicle_photos	array<string>	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/drivers/wizard?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "user": {6    "email": "driver@example.com",7    "phone": "+1234567890",8    "password": "SecurePass123!",9    "first_name": "John",10    "last_name": "Driver"11  },12  "vehicle_ids": [13    "vehicle-uuid-1",14    "vehicle-uuid-2"15  ],16  "primary_vehicle_id": "vehicle-uuid-1",17  "license_number": "DL12345678",18  "all_zones": false,19  "zone_ids": [20    "uuid1",21    "uuid2"22  ],23  "preferred_zone_ids": [24    "uuid1"25  ],26  "status": "active",27  "national_id": "1234567890",28  "bank_info": {29    "bank_name": "Example Bank",30    "iban": "IQ00XXXX"31  },32  "address": {33    "line1": "Street 1",34    "city": "Baghdad"35  },36  "identity_card_photos": [37    "https://example.com/id-front.jpg",38    "https://example.com/id-back.jpg"39  ],40  "driving_licence_photos": [41    "https://example.com/licence-front.jpg"42  ],43  "vehicle_photos": [44    "https://example.com/car-front.jpg",45    "https://example.com/car-side.jpg"46  ]47}'

Response examples

201 · Success409 · Phone Already Registered409 · Email Already Registered

201Created

Response body

json

1{2  "success": true,3  "message": "Driver created successfully",4  "driver": {5    "id": "uuid"6  }7}

Update Driver

Delivery & Last-Mile / Drivers

PUT/delivery/drivers/:driverId

Update an existing driver with both user and driver information in a single API call. Optimized for driver mobile applications. Requires manage:operations:tenant permission.

• Type: JWT Bearer Token

• Permissions: Requires manage:operations:tenant or user must be a system admin.

User Information (optional)

• first_name (string): Driver's first name

• last_name (string): Driver's last name

• phone (string): Driver's phone number

• avatar_url (string): Driver's profile picture URL

• profile_data (object): Additional user profile information

Driver Information (optional)

• vehicle_id (string, UUID): Assign different vehicle to driver

• vehicle_ids (array of UUIDs): Full vehicle assignment list; omit all of vehicle_id, vehicle_ids, and primary_vehicle_id to update profile only without touching vehicle assignments

• primary_vehicle_id (string, UUID): Primary vehicle; must be included in vehicle_ids when both are sent

• license_number (string): Driver's license number

• all_zones (boolean): If true, driver can operate in all zones. If false, driver can only operate in zones specified in zone_ids. Cannot be set to true if zone_ids is provided

• zone_ids (array of UUIDs): Delivery zones for the driver. Required if all_zones is false. Cannot be provided if all_zones is true

• preferred_zone_ids (array of UUIDs): Preferred zones for auto-assignment. Omitted = unchanged; [] = clear. When the driver does not have all-zones access (see below), every id must belong to the driver’s selected zones: same-request zone_ids if provided, otherwise current delivery_zone_drivers assignments. When all_zones is true (from body or already on the driver if body omits it), subset check is skipped.

• status (string): Driver status (active, inactive, etc.)

• driver_details (object): Additional driver-specific information (nested bank_info, national_id, address are written to columns and stripped from stored JSON)

• bank_info (object): Bank fields → drivers.bank_info

• national_id (string): → drivers.national_id

• address (object or string): → drivers.address JSONB

• current_latitude (number): Current latitude position

• current_longitude (number): Current longitude position

• is_online (boolean): Driver's online status

Validation Rules

• preferred_zone_ids must be tenant delivery_zones ids

• Subset rule: required only when effective all_zones is false (request all_zones: true overrides; if all_zones omitted, uses stored drivers.all_zones)

• Assigned set for subset: request zone_ids when present, else existing zone assignments

• When updating zone_ids while all_zones is false: 409 if the driver has an assigned delivery that is not terminal (delivered / failed / cancelled / returned) and has pickup_zone_id or dropoff_zone_id set to a zone not in the new zone_ids (legs with null zone id are ignored)

Note

used_capacity_unit is read-only and managed automatically by the backend.

Path parameters

Parameter	Type	Description
driverIdRequired	string	ID of the driver to update (string, UUID, required): The unique identifier of the driver to update. ID of the driver to update (string, UUID, required): The unique identifier of the driver to update. Example: uuid

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Bearer {{access_token}} Bearer {{access_token}} Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
first_name	string	—
last_name	string	—
phone	string	—
avatar_url	string	—
profile_data	object	—
profile_data.bio	string	—
vehicle_ids	array<string>	—
primary_vehicle_id	string	—
license_number	string	—
all_zones	boolean	—
zone_ids	array<string>	—
preferred_zone_ids	array<string>	—

Show 16 more body fields

Additional body parameters

Parameter	Type	Description
status	string	—
national_id	string	—
bank_info	object	—
bank_info.bank_name	string	—
bank_info.account_number	string	—
address	object	—
address.line1	string	—
address.city	string	—
identity_card_photos	array<string>	—
driving_licence_photos	array<string>	—
vehicle_photos	array<string>	—
driver_details	object	—
driver_details.rating	number	—
current_latitude	number	—
current_longitude	number	—
is_online	boolean	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "first_name": "John",6  "last_name": "Smith",7  "phone": "+1234567890",8  "avatar_url": "https://example.com/new-avatar.jpg",9  "profile_data": {10    "bio": "Experienced driver with 5 years experience"11  },12  "vehicle_ids": [13    "new-vehicle-uuid",14    "backup-vehicle-uuid"15  ],16  "primary_vehicle_id": "new-vehicle-uuid",17  "license_number": "DL87654321",18  "all_zones": false,19  "zone_ids": [20    "zone-uuid-1",21    "zone-uuid-2"22  ],23  "preferred_zone_ids": [24    "zone-uuid-1"25  ],26  "status": "active",27  "national_id": "1234567890",28  "bank_info": {29    "bank_name": "Example Bank",30    "account_number": "000111"31  },32  "address": {33    "line1": "Street 1",34    "city": "Baghdad"35  },36  "identity_card_photos": [37    "https://example.com/id-front.jpg",38    "https://example.com/id-back.jpg"39  ],40  "driving_licence_photos": [41    "https://example.com/licence-front.jpg"42  ],43  "vehicle_photos": [44    "https://example.com/car-front.jpg"45  ],46  "driver_details": {47    "rating": 4.948  },49  "current_latitude": 37.7849,50  "current_longitude": -122.4094,51  "is_online": true52}'

Response examples

200 · Success Response409 · Conflict - zone shrink blocked by active delivery403 · Error - Insufficient Permissions

200OK

Response body

json

1{2  "success": true,3  "message": "Driver updated successfully",4  "driver": {5    "driver_id": "driver-uuid-123",6    "license_number": "DL87654321",7    "status": "active",8    "driver_details": {},9    "documents": {10      "avatar": [11        "https://example.com/new-avatar.jpg"12      ],13      "identity_card_photos": [14        "https://example.com/id-front.jpg",15        "https://example.com/id-back.jpg"16      ],17      "driving_licence_photos": [18        "https://example.com/licence-front.jpg"19      ],20      "vehicle_photos": [21        "https://example.com/car-front.jpg"22      ]23    },24    "is_online": true,25    "all_zones": false,26    "preferred_zone_ids": [27      "zone-uuid-1"28    ],29    "used_capacity_unit": 30,30    "current_location": {31      "latitude": 37.7849,32      "longitude": -122.4094,33      "last_update": "2023-08-01T16:00:00Z"34    },35    "user_id": "user-uuid-def",36    "first_name": "John",37    "last_name": "Smith",38    "phone": "+1234567890",39    "avatar_url": "https://example.com/new-avatar.jpg",40    "profile_data": {},41    "vehicle": {42      "id": "new-vehicle-uuid",43      "name": "Truck 202",44      "code": "TRK002",45      "image_url": "https://example.com/truck.jpg",46      "capacity_unit": 10047    },48    "updated_at": "2023-08-01T16:00:00Z"49  }50}

Delete Driver

Delivery & Last-Mile / Drivers

DELETE/delivery/drivers/:driverId

Soft delete a driver (changes status to inactive). The driver can delete themselves, or this can be done by a user with manage:users:tenant permission.

Path parameters

Parameter	Type	Description
driverIdRequired	string	ID of the driver to delete ID of the driver to delete Example: uuid

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

1{2  "success": true,3  "message": "Driver deleted successfully"4}

Update Driver Location

Delivery & Last-Mile / Drivers

POST/delivery/drivers/:driverId/location

Update a driver's current location. The driver can update their own location, or this can be done by a user with manage:operations:tenant permission.

Path parameters

Parameter	Type	Description
driverIdRequired	string	ID of the driver whose location to update ID of the driver whose location to update Example: uuid

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
latitude	number	—
longitude	number	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}/location?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "latitude": 37.7749,6  "longitude": -122.41947}'

Response examples

200 · Success Response400 · Error - Missing Location Data

200OK

Response body

json

1{2  "success": true,3  "message": "Driver location updated successfully",4  "timestamp": "2023-08-01T15:30:00Z",5  "driver": {6    "id": "uuid",7    "current_latitude": 37.7749,8    "current_longitude": -122.4194,9    "last_location_update": "2023-08-01T15:30:00Z"10  }11}

Switch Primary Vehicle (Driver)

Delivery & Last-Mile / Drivers

POST/delivery/driver/primary-vehicle

Switch the logged-in driver's primary vehicle. The driver can only switch among vehicles already assigned to them. The switch will be rejected if the driver's current used capacity exceeds the target vehicle's capacity.

• Type: JWT Bearer Token

• The driver is resolved from the authenticated user; no driverId path parameter is required.

Validation Rules

• vehicle_id is required and must be a string.

• The vehicle must be assigned to the current driver.

• The vehicle must be active and not soft-deleted.

• The driver's used_capacity_unit must be less than or equal to the vehicle's capacity_unit. If used_capacity_unit is greater, the request fails with a capacity error.

Responses

Returns the updated driver profile with new primary vehicle information.

When the driver's used capacity is greater than the target vehicle's capacity.

If the vehicle is not assigned to the driver or does not exist.

If the authenticated user is not a driver in the tenant.

For unexpected server or database issues.

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language for response messages Preferred language for response messages Example: en

Headers

Parameter	Type	Description
Authorization	string	Bearer {{access_token}} Bearer {{access_token}} Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
vehicle_idRequired	string	(string, UUID, required): The ID of the vehicle to make primary. Must be already assigned to the driver. (string, UUID, required): The ID of the vehicle to make primary. Must be already assigned to the driver.

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/driver/primary-vehicle?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "vehicle_id": "vehicle-uuid-1"6}'

Response examples

200 · Success400 · Error (400 Bad Request - Capacity Exceeded)404 · Error (404 Not Found - Vehicle Not Assigned)404 · Error (404 Not Found - Driver Not Found)500 · Error (500 Internal Server Error)

200OK

Response body

json

1{2  "success": true,3  "message": "Driver updated successfully",4  "driver": {5    "driver_id": "driver-uuid-123",6    "primary_vehicle_id": "vehicle-uuid-1",7    "vehicle": {8      "id": "vehicle-uuid-1",9      "name": "Van 101",10      "capacity_unit": 50,11      "is_primary": true12    },13    "vehicles": [14      {15        "id": "vehicle-uuid-1",16        "name": "Van 101",17        "capacity_unit": 50,18        "is_primary": true19      },20      {21        "id": "vehicle-uuid-2",22        "name": "Small Car",23        "capacity_unit": 10,24        "is_primary": false25      }26    ],27    "used_capacity_unit": 2028  }29}

Get Driver Wallet Transactions

Delivery & Last-Mile / Drivers

GET/delivery/drivers/:driverId/wallet-transactions

Get a driver's wallet transaction list with filters for search, date range, type, source, recorded actor, and payment method.

Contract

• Returns only rows from wallet_transactions for the driver's wallet.

• Does not include cod_collections rows. Use /delivery/cod-collections or /delivery/cod-summary for COD cash collection/liability records.

• id is always the wallet_transactions.id value.

• Existing source remains the compatibility category: Support when the description contains support, otherwise Order for a linked delivery or Support for other rows.

• transaction_source is the literal stored metadata source, or null when unavailable.

• recorded_by is {id, name} when actor metadata exists, otherwise null. A saved actor-name snapshot is preferred; older rows without one use the current profile name of the saved actor ID. Missing names remain null; no actor is inferred from the delivery or wallet owner.

• data.source_options is the sorted distinct non-empty raw transaction sources from the full displayed wallet history (earning, transfer, payment, or support-description rows). Options are independent of pagination, date range, and other filters, and remain available when the filtered result is empty.

• data.summary.current_balance is the wallet's usable balance.

• data.summary.reserved is the total currently held for draft delivery fees. Reserved funds are not ledger transactions until captured.

• Currency is not returned; the frontend uses tenant configuration.

• pagination.total, total_credited, and total_debited use the same full filtered result before pagination. Filtering, totals, and pagination run in the database, so older matching rows are not limited to the first 1,000 wallet entries.

• source (optional category: cod, order, support; case-insensitive). cod is accepted for the existing Source dropdown and returns no matching rows while this wallet-only ledger contains only Order/Support categories; it never adds COD cash collection records.

Errors

HTTP 400 for invalid parameters or missing tenant context, 404 for a driver outside the selected tenant or unavailable driver, and 500 for a failed data read. Response messages are localized.

Frontend integration contract

Keep one existing Source column. When transaction_source is exactly manual_credit or manual_debit, display a single localized Manual label; otherwise preserve the existing category display from source. Keep the dropdown's COD/Order/Support options; add Manual credit and Manual debit only when their exact values are present in data.source_options. Existing category choices submit top-level source; manual choices submit top-level transaction_source. Clear the other source parameter when changing between category and manual choices. Do not add a separate Transaction Source column. Render Recorded By from recorded_by.name and send its text filter as actor_name. A legacy actor name may reflect the actor's current profile name rather than the name at recording time. Treat every item in data.transactions as a wallet transaction row. Display usable funds from data.summary.current_balance, reserved funds from data.summary.reserved, and currency from tenant configuration. Do not use this endpoint for COD collection selection, remittance, or COD cash liability display.

Path parameters

Parameter	Type	Description
driverIdRequired	string	Example: uuid

Query parameters

Parameter	Type	Description
tenant_id	string	(required when tenant is not resolved from auth context) (required when tenant is not resolved from auth context)
pageOptional	string	(optional, default 1) (optional, default 1) Example: 1
limitOptional	string	(optional, default 15, max 100) (optional, default 15, max 100) Example: 15
searchOptional	string	(optional, matches description, driver/customer phone/name, reference, or delivery code) (optional, matches description, driver/customer phone/name, reference, or delivery code)
from_dateOptional	string	/ to_date (optional, filters wallet_transactions.created_at) / to_date (optional, filters wallet_transactions.created_at)
to_date	string	—
typeOptional	string	(optional: debtor, creditor) (optional: debtor, creditor)
source	string	—
transaction_sourceOptional	string	Exact saved value from data.source_options (optional: exact, case-sensitive saved source selected from data.source_options) Exact saved value from data.source_options (optional: exact, case-sensitive saved source selected from data.source_options)
actor_nameOptional	string	Literal case-insensitive substring of recorded_by.name (optional: case-insensitive literal substring of the returned recorded_by.name; wildcard and regex characters are ordinary text) are trimmed; empty values are ignored. Literal case-insensitive substring of recorded_by.name (optional: case-insensitive literal substring of the returned recorded_by.name; wildcard and regex characters are ordinary text) are trimmed; empty values are ignored.
payment_methodOptional	string	(optional: cash, wallet, card) (optional: cash, wallet, card)
language	string	Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}/wallet-transactions?tenant_id=&page=1&limit=15&search=&from_date=&to_date=&type=&source=&transaction_source=&actor_name=&payment_method=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

1{2  "success": true,3  "message": "Driver wallet transactions retrieved successfully",4  "data": {5    "transactions": [6      {7        "id": "wallet-transaction-uuid",8        "amount": 10000,9        "type": "debtor",10        "source": "Support",11        "payment_method": "Wallet",12        "short_description": "COD settlement by wallet",13        "driver_name": "Driver Name",14        "driver_phone": "+9647700000000",15        "commission_amount": null,16        "user": null,17        "created_at": "2026-06-25T10:00:00.000Z",18        "delivery_id": null,19        "delivery_code": null,20        "external_reference_id": null,21        "status": null,22        "transaction_source": "cod_remittance",23        "recorded_by": null24      },25      {26        "id": "manual-wallet-transaction-uuid",27        "amount": 500,28        "type": "creditor",29        "source": "Support",30        "payment_method": "Wallet",31        "short_description": "Manual credit: Performance bonus",32        "driver_name": "Driver Name",33        "driver_phone": "+9647700000000",34        "commission_amount": null,35        "user": null,36        "created_at": "2026-06-25T10:00:00.000Z",37        "delivery_id": null,38        "delivery_code": null,39        "external_reference_id": null,40        "status": null,41        "transaction_source": "manual_credit",42        "recorded_by": {43          "id": "actor-user-uuid",44          "name": "Finance User"45        }46      }47    ],48    "pagination": {49      "page": 1,50      "limit": 15,51      "total": 252    },53    "summary": {54      "current_balance": 0,55      "reserved": 2500,56      "total_credited": 500,57      "total_debited": 1000058    },59    "source_options": [60      "cod_remittance",61      "manual_credit"62    ]63  }64}

Get Driver Accounting

Delivery & Last-Mile / Drivers

GET/delivery/drivers/:driverId/accounting

Get a driver's accounting summary for the selected period.

Cash allocation rules

• cash_collected.total is the total physical cash collected by the driver in the selected period.

• cash_collected.breakdown.cod and cash_collected.allocations.cod are only the goods/COD portion from cod_collections.allocations.cod.

• cash_collected.breakdown.order_fee and cash_collected.allocations.delivery_fee are the delivery-fee cash portion from cod_collections.allocations.delivery_fee.

• order_costs.breakdown.cash and order_costs.breakdown.wallet remain total settled/remitted cash amounts; use cash_cod, cash_delivery_fee, wallet_cod, and wallet_delivery_fee when the UI needs the split.

Frontend integration contract

Show cash_collected.total as total cash held/collected. Show COD from cash_collected.allocations.cod and delivery fee from cash_collected.allocations.delivery_fee; do not treat cash_collected.total as COD.

Path parameters

Parameter	Type	Description
driverIdRequired	string	Example: uuid

Query parameters

Parameter	Type	Description
tenant_id	string	—
from_date	string	—
to_date	string	—
language	string	Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}/accounting?tenant_id=&from_date=&to_date=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

1{2  "success": true,3  "message": "Driver accounting retrieved successfully",4  "data": {5    "period": {6      "from_date": null,7      "to_date": null8    },9    "currency": "IQD",10    "balance_summary": {11      "amount": 0,12      "type": "creditor",13      "description": "Driver wallet is settled."14    },15    "cash_collected": {16      "total": 60,17      "breakdown": {18        "cod": 50,19        "order_fee": 1020      },21      "allocations": {22        "cod": 50,23        "delivery_fee": 1024      }25    },26    "earnings": {27      "total": 0,28      "breakdown": {29        "cash": 0,30        "online_credit": 031      }32    },33    "order_costs": {34      "total": 60,35      "breakdown": {36        "cash": 60,37        "cash_cod": 50,38        "cash_delivery_fee": 10,39        "paid_by_receiver": 0,40        "card": 0,41        "wallet": 0,42        "wallet_cod": 0,43        "wallet_delivery_fee": 044      }45    },46    "company_earnings": 0,47    "paid_withdrawals": 0,48    "from_support": {49      "cod_type_creditor": 0,50      "cod_type_debtor": 0,51      "support_type_creditor": 0,52      "support_type_debtor": 053    }54  }55}

Get Driver Operation Status History

Delivery & Last-Mile / Drivers

GET/delivery/drivers/:driverId/operation-status-history

Get paginated history of a driver's operation_status changes (available / on_leave / idle). Each record includes old_status, new_status, changed_by, and changed_at.

Path parameters

Parameter	Type	Description
driverIdRequired	string	Example: uuid

Query parameters

Parameter	Type	Description
tenant_id	string	—
page	string	Example: 1
limit	string	Example: 20

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/drivers/${DRIVERID}/operation-status-history?tenant_id=&page=1&limit=20" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

1{2  "success": true,3  "history": [4    {5      "id": "uuid",6      "driver_id": "uuid",7      "tenant_id": "uuid",8      "old_status": "available",9      "new_status": "on_leave",10      "changed_by": "uuid",11      "changed_at": "2026-04-27T12:00:00Z"12    }13  ],14  "page": 1,15  "limit": 20,16  "total": 117}