Towit API Docs

Plain HTML docs served directly by the API. No Swagger JavaScript required.

Base URL https://api.towit.ai
Auth Header x-api-key: <TOWIT_API_KEY>
Health Check GET /health
Machine Spec /docs/openapi.json

Routes

GET /health

Health check

Public health check for the API and database connection.

Responses200 API and database are available
GET /v1/customers

List customers

Paramslimit
Responses200 Recent customers401
POST /v1/customers

Create or update customer

Creates a customer, or updates an existing customer when phone_e164 already exists.

Example Body
{
  "full_name": "Example Customer",
  "phone_e164": "+447700900123",
  "email": "customer@example.com",
  "customer_type": "private",
  "source_channel": "whatsapp",
  "notes": "Prefers WhatsApp updates"
}
Responses201 Customer created or updated400 401
POST /v1/whatsapp/intake

Process inbound customer WhatsApp message

Creates or updates the customer, active transport job, inbound message, outbound reply, and quote when distance can be calculated from supplied miles or pickup/delivery postcodes.

Example Body
{
  "from_phone_e164": "+447700900123",
  "customer_name": "Example Customer",
  "message_id": "wamid.example",
  "body": "Hi, quote please. Reg AB12CDE, starts and drives, from B1 1AA to M1 1AE, open trailer, private customer.",
  "customer_type": "private"
}
Responses201 WhatsApp intake saved and reply generated400 401
GET /v1/jobs

List jobs

Paramslimitstatus
Responses200 Recent jobs401
POST /v1/jobs

Create job

Creates a structured vehicle transport job. Existing IDs, nested objects, or a mix of both are accepted.

Example Body
{
  "customer": {
    "full_name": "Example Customer",
    "phone_e164": "+447700900123",
    "customer_type": "private"
  },
  "vehicle": {
    "registration": "AB12CDE",
    "make": "BMW",
    "model": "3 Series",
    "condition_status": "starts_drives",
    "has_keys": true
  },
  "pickup_location": {
    "postcode": "B1 1AA",
    "town_city": "Birmingham"
  },
  "delivery_location": {
    "postcode": "M1 1AE",
    "town_city": "Manchester"
  },
  "trailer_preference": "open",
  "requested_by_channel": "whatsapp",
  "source_message_id": "whatsapp-message-id"
}
Responses201 Job created400 401
GET /v1/jobs/{id}

Get job

Paramsid
Responses200 Job details401 404
PATCH /v1/jobs/{id}/status

Update job status

Paramsid
Example Body
{
  "status": "quote_needed",
  "actor_type": "openclaw",
  "notes": "Pickup and delivery postcodes collected"
}
Responses200 Job status updated400 401 404
POST /v1/jobs/{id}/messages

Store job message

Paramsid
Example Body
{
  "channel": "whatsapp",
  "external_message_id": "provider-message-id",
  "direction": "inbound",
  "sender_label": "Customer",
  "body": "Pickup B1, delivery M1"
}
Responses201 Message stored400 401
POST /v1/jobs/{id}/quotes

Add quote

Paramsid
Example Body
{
  "status": "sent",
  "transport_type": "open",
  "distance_miles": 120,
  "customer_price": 264,
  "pricing_notes": "Private quote sent by operator"
}
Responses201 Quote added400 401
GET /v1/drivers

List drivers

Paramslimit
Responses200 Recent drivers401
POST /v1/drivers

Create driver

Example Body
{
  "full_name": "Driver Name",
  "phone_e164": "+447700900555",
  "email": "driver@example.com",
  "company_name": "Driver Ltd",
  "active": true,
  "transport_capability": [
    "open"
  ]
}
Responses201 Driver created400 401
GET /v1/drivers/onboarding

List driver onboarding queue

Responses200 Driver onboarding queue401
POST /v1/drivers/{id}/documents

Add driver document

Paramsid
Example Body
{
  "document_type": "insurance",
  "onboarding_stage": "stage_2",
  "file_url": "https://storage.example.com/insurance.pdf",
  "notes": "Expires June 2027"
}
Responses201 Driver document stored400 401
PATCH /v1/drivers/{id}/onboarding-status

Update driver onboarding status

Paramsid
Example Body
{
  "status": "towit_verified",
  "reviewed_by": "Paul",
  "notes": "Documents checked and approved"
}
Responses200 Driver onboarding status updated400 401
POST /v1/jobs/{id}/assignments

Assign job to driver

Only active drivers with onboarding_status towit_verified can receive jobs.

Paramsid
Example Body
{
  "driver_id": "00000000-0000-0000-0000-000000000000",
  "status": "offered",
  "notes": "Offer sent on WhatsApp"
}
Responses201 Assignment created400 401 404 409 Driver is not active and towit_verified