Create and edit drivers

Before you start

Run these examples on a trusted server with TAROT_API_KEY set in its environment. Use X-Tarot-API-Key on every request. Never expose the key in client-side code, including browser or mobile app code. See Getting an API key.

Drivers are reusable planning templates

A driver belongs to an organisation and is available across its scenarios—not just the scenario currently open. Planners select which drivers to use for each scenario. Creating a driver does not automatically select it for every scenario.

Think of optimisation as rubber-stamping the selected driver template into a scenario-specific run: shift times, capacity, skills, route-end settings, contact details, and other defaults are copied when the run is created. A run also retains its driver association, but it is not a live view of all driver settings.

Editing a driver changes the reusable template for future planning; it does not automatically rewrite those copied fields on existing runs. Review already-planned runs separately in Tarot. A driver resource is also distinct from a login account: creating one does not create a Driver App user.

Find existing drivers

GET /v3/core/drivers?page=1&per_page=100

curl --fail-with-body -X GET "https://api.optimiser.app/v3/core/drivers?page=1&per_page=100" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY"

import os, requests

response = requests.get(
    "https://api.optimiser.app/v3/core/drivers?page=1&per_page=100",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.json())

const response = await fetch(`https://api.optimiser.app/v3/core/drivers?page=1&per_page=100`, {
  method: "GET",
  headers: {
    "X-Tarot-API-Key": process.env.TAROT_API_KEY,
  },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

Collection responses contain data, page, per_page, total_pages, and total_count, not a bare array. Process data, then request each subsequent page through total_pages, preserving your filters. Examples show the first page only.

Match your driver by uid and organisation, and retain its numeric id. Ensure you have the driver’s numeric ID from this list or the create-driver response. The edit examples assume it is available in the DRIVER_ID environment variable. A single driver can be retrieved with GET /v3/core/drivers/{driver_id}.

Create a driver

Replace organisation_id with your organisation’s numeric ID and use a stable, recognisable uid. Driver operations require the key’s role to have user-level access to that organisation.

Prepare a JSON request body like the following. The examples assume it is available in driver.json.

{
  "uid": "DRIVER-001",
  "organisation_id": 123,
  "shift_start": "08:00:00",
  "shift_end": "17:00:00",
  "location": {
    "address": "1 Martin Place, Sydney NSW 2000, Australia",
    "lat": -33.8679,
    "lon": 151.2073
  },
  "route_end": "start",
  "email": "driver@example.com",
  "speed_multiplier": 1.0
}

POST /v3/core/drivers

curl --fail-with-body -X POST "https://api.optimiser.app/v3/core/drivers" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @driver.json

import os, requests, json

with open("driver.json") as file:
    payload = json.load(file)

response = requests.post(
    "https://api.optimiser.app/v3/core/drivers",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

import { readFile } from "node:fs/promises";

const payload = await readFile("driver.json", "utf8");

const response = await fetch(`https://api.optimiser.app/v3/core/drivers`, {
  method: "POST",
  headers: {
    "X-Tarot-API-Key": process.env.TAROT_API_KEY,
    "Content-Type": "application/json",
  },
  body: payload,
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

HTTP 201 returns the created driver object. Save its id. Inspect existing drivers before repeating a create request; do not assume this endpoint upserts by uid.

Important driver fields

See DriverSchema schema reference for all fields, including billing defaults and territories.

Edit an existing driver

Send only the fields you want to change. This example extends the shift and updates the contact email. The ID belongs in the URL; the request body need not repeat it.

Prepare a JSON request body containing your changes. The examples assume it is available in driver-update.json.

{
  "shift_end": "18:00:00",
  "email": "updated-driver@example.com"
}

PATCH /v3/core/drivers/{ID}

curl --fail-with-body -X PATCH "https://api.optimiser.app/v3/core/drivers/${DRIVER_ID}" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @driver-update.json

import os, requests, json

with open("driver-update.json") as file:
    payload = json.load(file)

driver_id = os.environ["DRIVER_ID"]

response = requests.patch(
    f"https://api.optimiser.app/v3/core/drivers/{driver_id}",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

import { readFile } from "node:fs/promises";

const payload = await readFile("driver-update.json", "utf8");

const response = await fetch(`https://api.optimiser.app/v3/core/drivers/${process.env.DRIVER_ID}`, {
  method: "PATCH",
  headers: {
    "X-Tarot-API-Key": process.env.TAROT_API_KEY,
    "Content-Type": "application/json",
  },
  body: payload,
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

HTTP 200 returns the updated driver object. Confirm the changes and ask planners to review any affected future scenarios. Existing runs keep their copied settings unless separately changed.

Next, create scenarios and jobs to plan with your drivers.