Developers

Courivo API

A REST API to build on top of your courier operation — manage jobs, drivers, customers and invoices, and subscribe to webhooks.

Base URL: https://api.courivo.com/v1
Auth: Bearer token

Authentication

All requests require a Bearer token. Generate an API key in Dashboard → Settings → API, then send it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Jobs

GET/jobs

List jobs (newest first).

Example (curl)

curl -X GET https://api.courivo.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    {
      "id": "job_123",
      "status": "pending"
    }
  ],
  "pagination": {
    "total": 1
  }
}

POST/jobs

Create a job.

Request body

{
  "customer_id": "cus_123",
  "pickup_address": "10 Downing St, London",
  "drop_address": "Bullring, Birmingham",
  "priority": "standard"
}

Example (curl)

curl -X POST https://api.courivo.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_123","pickup_address":"10 Downing St, London","drop_address":"Bullring, Birmingham","priority":"standard"}'

Response

{
  "data": {
    "id": "job_123",
    "status": "pending"
  }
}

GET/jobs/{id}

Retrieve a single job.

Example (curl)

curl -X GET https://api.courivo.com/v1/jobs/{id} \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": {
    "id": "job_123",
    "status": "assigned"
  }
}

PATCH/jobs/{id}/status

Advance a job through its lifecycle.

Request body

{
  "status": "picked_up"
}

Example (curl)

curl -X PATCH https://api.courivo.com/v1/jobs/{id}/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"picked_up"}'

Response

{
  "data": {
    "id": "job_123",
    "status": "picked_up"
  }
}

Drivers

GET/drivers

List drivers with live status.

Example (curl)

curl -X GET https://api.courivo.com/v1/drivers \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    {
      "id": "drv_123",
      "first_name": "Mike",
      "status": "available"
    }
  ]
}

POST/drivers

Add a driver.

Request body

{
  "first_name": "Mike",
  "last_name": "Thompson",
  "email": "mike@example.com",
  "vehicle_type": "small_van"
}

Example (curl)

curl -X POST https://api.courivo.com/v1/drivers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Mike","last_name":"Thompson","email":"mike@example.com","vehicle_type":"small_van"}'

Response

{
  "data": {
    "id": "drv_123"
  }
}

PATCH/drivers/{id}

Update a driver.

Request body

{
  "vehicle_type": "large_van"
}

Example (curl)

curl -X PATCH https://api.courivo.com/v1/drivers/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_type":"large_van"}'

Response

{
  "data": {
    "id": "drv_123",
    "vehicle_type": "large_van"
  }
}

Customers

GET/customers

List customers.

Example (curl)

curl -X GET https://api.courivo.com/v1/customers \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    {
      "id": "cus_123",
      "company_name": "Apex Retail"
    }
  ]
}

POST/customers

Create a customer.

Request body

{
  "company_name": "Apex Retail Co.",
  "email": "orders@apex.co.uk"
}

Example (curl)

curl -X POST https://api.courivo.com/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Apex Retail Co.","email":"orders@apex.co.uk"}'

Response

{
  "data": {
    "id": "cus_123"
  }
}

Invoices

GET/invoices

List invoices.

Example (curl)

curl -X GET https://api.courivo.com/v1/invoices \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    {
      "id": "inv_123",
      "invoice_number": "INV-001",
      "status": "sent"
    }
  ]
}

POST/invoices

Create an invoice from delivered jobs.

Request body

{
  "customer_id": "cus_123",
  "job_ids": [
    "job_123",
    "job_124"
  ]
}

Example (curl)

curl -X POST https://api.courivo.com/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_123","job_ids":["job_123","job_124"]}'

Response

{
  "data": {
    "id": "inv_123",
    "invoice_number": "INV-001"
  }
}

POST/invoices/{id}/send

Email the invoice to the customer.

Example (curl)

curl -X POST https://api.courivo.com/v1/invoices/{id}/send \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": {
    "id": "inv_123",
    "status": "sent"
  }
}

Webhooks

Subscribe to events to be notified in real time. Courivo POSTs a signed JSON payload to your endpoint for each event below.

job.created	A new job was booked.
job.assigned	A driver was assigned to a job.
job.picked_up	A parcel was collected.
job.delivered	A delivery was completed.
job.cancelled	A job was cancelled.
invoice.paid	An invoice was paid.