Skip to content
Courier docs

Quickstart

This books one sandbox delivery from Trafalgar Square to Tower Hill. You need a sandbox key — see Sandbox and API keys — and the three variables set in your shell.

  1. Check your key works. A list of your jobs, empty or not, means you’re in.

    Terminal window
    curl -u "$COURIER_KEY:$COURIER_SECRET" "$COURIER_API/v1/jobs?size=1"

    A 401 means the key or the secret is wrong.

  2. Ask for a price. Coordinates for both ends, and the vehicle.

    Terminal window
    curl -u "$COURIER_KEY:$COURIER_SECRET" "$COURIER_API/v1/quotes" \
      -H 'Content-Type: application/json' \
      -d '{
        "pickup":  { "latitude": 51.5080, "longitude": -0.1281 },
        "dropoff": { "latitude": 51.5081, "longitude": -0.0759 },
        "vehicle": "bicycle"
      }'
    {
      "id": "0199d2c4-6b1e-7a42-9c35-2f0d8e1b7a10",
      "currency": "GBP",
      "total_amount_minor": 918,
      "total": "9.18 GBP",
      "distance_metres": 4454,
      "estimated_duration_seconds": 1047,
      "vehicle": "bicycle",
      "expires_at": "2026-10-10T12:14:00+00:00",
      "breakdown": [
        { "code": "base_fare", "description": "Base fare", "amount_minor": 300 },
        { "code": "distance", "description": "Distance (2.77 mi)", "amount_minor": 249 },
        { "code": "duration", "description": "Journey time (18 min)", "amount_minor": 216 },
        { "code": "tax", "description": "VAT (20%)", "amount_minor": 153 }
      ],
      "price_book_version": 1
    }

    The price holds for ten minutes. Keep the id.

  3. Book it. Against the quote, with who the courier collects from and delivers to. The Idempotency-Key header is required — see Retries and idempotency.

    Terminal window
    curl -u "$COURIER_KEY:$COURIER_SECRET" "$COURIER_API/v1/jobs" \
      -H 'Content-Type: application/json' \
      -H 'Idempotency-Key: order-1042' \
      -d '{
        "quote_id": "0199d2c4-6b1e-7a42-9c35-2f0d8e1b7a10",
        "pickup": {
          "latitude": 51.5080, "longitude": -0.1281,
          "address": "Trafalgar Square, London",
          "contact_name": "The kitchen", "contact_phone": "+44 20 7946 0100",
          "notes": "Ask at the counter."
        },
        "dropoff": {
          "latitude": 51.5081, "longitude": -0.0759,
          "address": "Tower Hill, London",
          "contact_name": "Alex Rivera", "contact_phone": "+44 7700 900456",
          "notes": "Second floor, buzzer 4."
        }
      }'
    {
      "id": "0199d2c5-1f3a-7d10-8b2e-6c4a9e0f2d31",
      "reference": "JOB-7F3K2Q",
      "status": "searching",
      "currency": "GBP",
      "price_amount_minor": 918,
      "vehicle": "bicycle",
      "tracking_url": "https://track.courier.example/4mZ8qPx2",
      "booked_at": "2026-10-10T12:04:31+00:00",
      "scheduled_for": null
    }

    searching means the offer is already out to couriers nearby. A job booked for later starts as pending instead, and starts searching twenty minutes before its time.

  4. Read it back. Whenever you like — this is what is true now.

    Terminal window
    curl -u "$COURIER_KEY:$COURIER_SECRET" "$COURIER_API/v1/jobs/0199d2c5-1f3a-7d10-8b2e-6c4a9e0f2d31"

Next

Section titled “Next”