Skip to main content

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:read or drivers:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
qstring
statusstring
subOrgIdstring
pageSizestring
cursorstring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].idstring
items[].tenantIdstring
items[].subOrgIdstringomitted when empty
items[].employeeNumberstring
items[].firstNamestring
items[].lastNamestring
items[].dateOfBirthstring
items[].nationalIdMaskedstringomitted when empty
items[].emailstringomitted when empty
items[].phonestringomitted when empty
items[].statusstring
items[].hireDatestring
items[].terminationDatestringomitted when empty
items[].licenseobject
items[].license.numberstring
items[].license.countrystring
items[].license.classesarray of string
items[].license.issuedAtstringomitted when empty
items[].license.expiresAtstring
items[].license.endorsementsarray of stringomitted when empty
items[].license.LocalClass—
items[].license.authoritystringomitted when empty
items[].license.localClassstringomitted when empty
items[].licenseValidboolean
items[].qualificationsarray of object
items[].qualifications[].codestring
items[].qualifications[].issuedAtstring
items[].qualifications[].expiresAtstringomitted when empty
items[].qualifications[].issuingBodystringomitted when empty
items[].homeRegionstringomitted when empty
items[].languagesarray of string
items[].assignableboolean
items[].nationalitystringomitted when empty
items[].employmentstring
items[].contractorCompanystringomitted when empty
items[].photoobjectmay be null
items[].photo.contentTypestring
items[].photo.sizeinteger
items[].photo.updatedAtstring
items[].photo.updatedBystringomitted when empty
items[].createdAtstring
items[].updatedAtstring
items[].versioninteger
nextCursorstring
totalinteger

Example​

curl "https://api.zaitrack.app/v1/drivers" \
-H "Authorization: Bearer zk_test_…"

Hire a driver​

POST /v1/drivers

  • Scope: drivers:write or drivers:*
  • 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.

FieldTypeNotes
subOrgIdstring
employeeNumberstring
firstNamestring
lastNamestring
dateOfBirthstring
hireDatestring
nationalIdstring
emailstring
phonestring
homeRegionstring
languagesarray of string
licenseobject
license.numberstring
license.countrystring
license.classesarray of string
license.issuedAtstringoptional
license.expiresAtstring
license.endorsementsarray of stringoptional
license.LocalClass—
license.authoritystringoptional
license.localClassstringoptional
nationalitystring
employmentstring
contractorCompanystring

Response​

201: fields the handler writes, taken from its source.

FieldTypeNotes
idstring
tenantIdstring
subOrgIdstringomitted when empty
employeeNumberstring
firstNamestring
lastNamestring
dateOfBirthstring
nationalIdMaskedstringomitted when empty
emailstringomitted when empty
phonestringomitted when empty
statusstring
hireDatestring
terminationDatestringomitted when empty
licenseobject
license.numberstring
license.countrystring
license.classesarray of string
license.issuedAtstringomitted when empty
license.expiresAtstring
license.endorsementsarray of stringomitted when empty
license.LocalClass—
license.authoritystringomitted when empty
license.localClassstringomitted when empty
licenseValidboolean
qualificationsarray of object
qualifications[].codestring
qualifications[].issuedAtstring
qualifications[].expiresAtstringomitted when empty
qualifications[].issuingBodystringomitted when empty
homeRegionstringomitted when empty
languagesarray of string
assignableboolean
nationalitystringomitted when empty
employmentstring
contractorCompanystringomitted when empty
photoobjectmay be null
photo.contentTypestring
photo.sizeinteger
photo.updatedAtstring
photo.updatedBystringomitted when empty
createdAtstring
updatedAtstring
versioninteger

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:read or drivers:*
  • 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:write or drivers:*
  • 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.

FieldTypeNotes
firstNamestringoptional
lastNamestringoptional
emailstringoptional
phonestringoptional
homeRegionstringoptional
languagesarray of stringoptional
subOrgIdstringoptional
nationalitystringoptional
employmentstringoptional
contractorCompanystringoptional

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:write or drivers:*
  • 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)"