Drivers: basics
5 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.
Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.
List drivers
GET /v1/drivers
- Scope:
drivers:readordrivers:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
| Query parameter | Type | Notes |
|---|---|---|
q | string | |
status | string | |
subOrgId | string | |
pageSize | string | |
cursor | string |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].id | string | |
items[].tenantId | string | |
items[].subOrgId | string | omitted when empty |
items[].employeeNumber | string | |
items[].firstName | string | |
items[].lastName | string | |
items[].dateOfBirth | string | |
items[].nationalIdMasked | string | omitted when empty |
items[].email | string | omitted when empty |
items[].phone | string | omitted when empty |
items[].status | string | |
items[].hireDate | string | |
items[].terminationDate | string | omitted when empty |
items[].license | object | |
items[].license.number | string | |
items[].license.country | string | |
items[].license.classes | array of string | |
items[].license.issuedAt | string | omitted when empty |
items[].license.expiresAt | string | |
items[].license.endorsements | array of string | omitted when empty |
items[].license.LocalClass | — | |
items[].license.authority | string | omitted when empty |
items[].license.localClass | string | omitted when empty |
items[].licenseValid | boolean | |
items[].qualifications | array of object | |
items[].qualifications[].code | string | |
items[].qualifications[].issuedAt | string | |
items[].qualifications[].expiresAt | string | omitted when empty |
items[].qualifications[].issuingBody | string | omitted when empty |
items[].homeRegion | string | omitted when empty |
items[].languages | array of string | |
items[].assignable | boolean | |
items[].nationality | string | omitted when empty |
items[].employment | string | |
items[].contractorCompany | string | omitted when empty |
items[].photo | object | may be null |
items[].photo.contentType | string | |
items[].photo.size | integer | |
items[].photo.updatedAt | string | |
items[].photo.updatedBy | string | omitted when empty |
items[].createdAt | string | |
items[].updatedAt | string | |
items[].version | integer | |
nextCursor | string | |
total | integer |
Example
curl "https://api.zaitrack.app/v1/drivers" \
-H "Authorization: Bearer zk_test_…"
Hire a driver
POST /v1/drivers
- Scope:
drivers:writeordrivers:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
subOrgId | string | |
employeeNumber | string | |
firstName | string | |
lastName | string | |
dateOfBirth | string | |
hireDate | string | |
nationalId | string | |
email | string | |
phone | string | |
homeRegion | string | |
languages | array of string | |
license | object | |
license.number | string | |
license.country | string | |
license.classes | array of string | |
license.issuedAt | string | optional |
license.expiresAt | string | |
license.endorsements | array of string | optional |
license.LocalClass | — | |
license.authority | string | optional |
license.localClass | string | optional |
nationality | string | |
employment | string | |
contractorCompany | string |
Response
201: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | string | |
tenantId | string | |
subOrgId | string | omitted when empty |
employeeNumber | string | |
firstName | string | |
lastName | string | |
dateOfBirth | string | |
nationalIdMasked | string | omitted when empty |
email | string | omitted when empty |
phone | string | omitted when empty |
status | string | |
hireDate | string | |
terminationDate | string | omitted when empty |
license | object | |
license.number | string | |
license.country | string | |
license.classes | array of string | |
license.issuedAt | string | omitted when empty |
license.expiresAt | string | |
license.endorsements | array of string | omitted when empty |
license.LocalClass | — | |
license.authority | string | omitted when empty |
license.localClass | string | omitted when empty |
licenseValid | boolean | |
qualifications | array of object | |
qualifications[].code | string | |
qualifications[].issuedAt | string | |
qualifications[].expiresAt | string | omitted when empty |
qualifications[].issuingBody | string | omitted when empty |
homeRegion | string | omitted when empty |
languages | array of string | |
assignable | boolean | |
nationality | string | omitted when empty |
employment | string | |
contractorCompany | string | omitted when empty |
photo | object | may be null |
photo.contentType | string | |
photo.size | integer | |
photo.updatedAt | string | |
photo.updatedBy | string | omitted when empty |
createdAt | string | |
updatedAt | string | |
version | integer |
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X POST "https://api.zaitrack.app/v1/drivers" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"subOrgId": "…", "employeeNumber": "…", "firstName": "…", "lastName": "…", "dateOfBirth": "…", "hireDate": "…", "nationalId": "…", "email": "…", "phone": "…", "homeRegion": "…", "languages": [], "license": {"number": "…", "country": "…", "classes": [], "issuedAt": "…", "expiresAt": "…", "endorsements": [], "LocalClass": null, "authority": "…", "localClass": "…"}, "nationality": "…", "employment": "…", "contractorCompany": "…"}'
Get a driver
GET /v1/drivers/{id}
- Scope:
drivers:readordrivers:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
Path parameters: id.
Request
No body.
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Hire a driver.
Example
curl "https://api.zaitrack.app/v1/drivers/$ID" \
-H "Authorization: Bearer zk_test_…"
Update a driver (If-Match version)
PATCH /v1/drivers/{id}
- Scope:
drivers:writeordrivers:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id.
Request
Fields the handler reads, taken from its source.
| Field | Type | Notes |
|---|---|---|
firstName | string | optional |
lastName | string | optional |
email | string | optional |
phone | string | optional |
homeRegion | string | optional |
languages | array of string | optional |
subOrgId | string | optional |
nationality | string | optional |
employment | string | optional |
contractorCompany | string | optional |
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Hire a driver.
Example
Every field is sent with a placeholder value: replace them with yours.
curl -X PATCH "https://api.zaitrack.app/v1/drivers/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"firstName": "…", "lastName": "…"}'
Activate a driver
POST /v1/drivers/{id}:activate
- Scope:
drivers:writeordrivers:* - Rate class:
write(50 per second and 36,000 per hour) - Idempotency-Key: optional
- Audited: no
- Step-up MFA: no
- If-Match: the version you read; a stale one is refused (412 or 409)
Path parameters: id.
Request
No body: the handler reads none.
Response
200: fields the handler writes, taken from its source.
The same fields as the response of Hire a driver.
Example
curl -X POST "https://api.zaitrack.app/v1/drivers/$ID:activate" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)"