Drivers

Manage the people who operate your fleet vehicles — list, create, and update driver profiles.

Prerequisites

All endpoints require a valid JWT token, API key, and tenant header. See Authentication.

---

List Drivers

Retrieve a paginated list of drivers with filtering support.

GET/apidev/v1/fleet/drivers

PermissionAPICLI_FLEET_DRIVERS_READ

Rate Limit30 req/min (sliding window)

Cache120s

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	25	Records per page. Min: 1, Max: 100
offset	integer	No	0	Records to skip
status	string	No	—	A (active) or I (inactive)
name	string	No	—	Partial match on driver name or email. Max length 80
document	string	No	—	Partial match on document number. Max length 30
driver_group	string	No	—	Partial match on driver group name. Max length 80

Response Fields

Field	Type	Description
id	string	Driver unique identifier (BigInt as string)
name	string | null	Driver full name
document	string | null	Identity document number
email	string | null	Email address
phone	string | null	Phone number
image_url	string | null	URL to driver photo
external_code	string | null	External integration code
active	boolean	Whether the driver is currently active
status	string	"A" (active) or "I" (inactive)
driver_group	string | null	Driver group or category
assigned_vehicle	object | null	Assigned vehicle (see below)

assigned_vehicle object:

Field	Type	Description
id	string	Vehicle identifier
name	string | null	Vehicle display name
license_plate	string | null	Vehicle license plate

Code Example

cURL

curl -s "https://$TENANT/apidev/v1/fleet/drivers?limit=10&status=A" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers?limit=10&status=A`,
  { headers }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} drivers`);

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/drivers",
    headers=headers,
    params={"limit": 10, "status": "A"},
)

result = response.json()
for driver in result["data"]:
    vehicle = driver["assigned_vehicle"]
    print(f"{driver['name']} — {vehicle['name'] if vehicle else 'Unassigned'}")

Example Response

{
  "success": true,
  "data": [
    {
      "id": "104820579455",
      "name": "Carlos Martinez",
      "document": "12345678",
      "email": "carlos@company.com",
      "phone": "+59899654321",
      "image_url": null,
      "external_code": "DRV-042",
      "active": true,
      "status": "A",
      "driver_group": "Long Haul",
      "assigned_vehicle": {
        "id": "104820579301",
        "name": "Movil 10",
        "license_plate": "ABC123"
      }
    },
    {
      "id": "104820579460",
      "name": "Maria Lopez",
      "document": "87654321",
      "email": "maria@company.com",
      "phone": "+59899123456",
      "image_url": null,
      "external_code": null,
      "active": true,
      "status": "A",
      "driver_group": "Urban",
      "assigned_vehicle": null
    }
  ],
  "meta": {
    "total": 28,
    "limit": 10,
    "offset": 0
  }
}

---

Create Driver

Create a new driver profile. Only name is required.

POST/apidev/v1/fleet/drivers

PermissionAPICLI_FLEET_DRIVERS_WRITE

Rate Limit30 req/min (sliding window)

CacheNone

Request Body

Field	Type	Required	Max Length	Description
name	string	Yes	40	Driver full name
document	string	No	30	Identity document number
document_type	number	No	—	Document type identifier
email	string	No	100	Email address
phone	string	No	20	Landline phone number
mobile	string	No	20	Mobile phone number
status	string	No	10	"A" or "I" (default: "A")
driver_type_id	string	No	40	Driver category identifier
vehicle_id	string	No	40	Vehicle to assign
supervisor_id	string	No	40	Supervising driver
external_code	string	No	20	External integration code
ibutton	string	No	40	iButton identification code
pin	string	No	20	Driver PIN
notes	string	No	2000	Free-text notes
image_url	string	No	500	URL to driver photo
street	string	No	200	Street address
street_number	string	No	10	Street number
apartment	string	No	10	Apartment or unit
corner	string	No	200	Cross street
country_id	string	No	40	Country identifier
department_id	string	No	40	Department/state identifier
latitude	string	No	40	Home address latitude
longitude	string	No	40	Home address longitude
birth_date	string	No	20	Date of birth (ISO 8601)
hire_date	string	No	20	Hire date (ISO 8601)
termination_date	string	No	20	Termination date (ISO 8601)
legal_name	string	No	60	Legal/business name
tax_id	string	No	40	Tax identification number

Code Example

cURL

curl -s -X POST "https://$TENANT/apidev/v1/fleet/drivers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Martinez",
    "document": "12345678",
    "document_type": 1,
    "email": "carlos@company.com",
    "mobile": "+59899654321",
    "vehicle_id": "104820579301"
  }'

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Carlos Martinez",
      document: "12345678",
      document_type: 1,
      email: "carlos@company.com",
      mobile: "+59899654321",
      vehicle_id: "104820579301",
    }),
  }
);

const { data } = await response.json();
console.log(`Driver created with ID: ${data.id}`);

Python

response = requests.post(
    f"https://{TENANT}/apidev/v1/fleet/drivers",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "name": "Carlos Martinez",
        "document": "12345678",
        "document_type": 1,
        "email": "carlos@company.com",
        "mobile": "+59899654321",
        "vehicle_id": "104820579301",
    },
)

result = response.json()
print(f"Driver created with ID: {result['data']['id']}")

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "104820579499"
  }
}

---

Update Driver

Update a driver profile. Only send the fields you want to change. Send null to clear a nullable field; name and status cannot be null (you get 400 VALIDATION_ERROR). An unknown {id} returns 404 NOT_FOUND even with an empty body.

PUT/apidev/v1/fleet/drivers/{id}

PermissionAPICLI_FLEET_DRIVERS_WRITE

Rate Limit30 req/min (sliding window)

CacheNone

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Driver unique identifier

Request Body

All fields from Create Driver are accepted, but none are required. See Partial Updates for the general pattern.

Five fields accept a different maximum length on update than on create:

Field	Max Length (update)
ibutton	100
street_number	20
apartment	20
legal_name	200
tax_id	50

All other fields keep the same limits as Create Driver.

Code Example

cURL

curl -s -X PUT "https://$TENANT/apidev/v1/fleet/drivers/104820579455" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.email@company.com",
    "phone": null,
    "vehicle_id": "104820579315"
  }'

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers/104820579455`,
  {
    method: "PUT",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "new.email@company.com",
      phone: null,
      vehicle_id: "104820579315",
    }),
  }
);

const { data } = await response.json();
console.log(`Updated: ${data.updated_fields.join(", ")}`);

Python

response = requests.put(
    f"https://{TENANT}/apidev/v1/fleet/drivers/104820579455",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "email": "new.email@company.com",
        "phone": None,
        "vehicle_id": "104820579315",
    },
)
print(response.json()["data"]["updated_fields"])

Example Response

{
  "success": true,
  "data": {
    "id": "104820579455",
    "updated_fields": ["email", "phone", "vehicle_id"]
  },
  "meta": {}
}

---

Errors

Code	HTTP	Applies to	Description
VALIDATION_ERROR	400	List, Create, Update	Invalid params or body (e.g., name missing on create, limit > 100)
UNAUTHORIZED	401	All	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	All	User lacks APICLI_FLEET_DRIVERS_READ or APICLI_FLEET_DRIVERS_WRITE
NOT_FOUND	404	Update	Driver ID doesn't exist or doesn't belong to your tenant
RATE_LIMITED	429	All	Exceeded 30 req/min

---

Related

• Devices API — Manage GPS devices assigned to drivers
• Telemetry — Ingest GPS positions from devices
• Pagination — Standard pagination parameters
• Partial Updates — How PUT endpoints work