Circle Routes integration reference

Overview

Circle Routes gives your operations team one integration layer for daily delivery work: send deliveries in, receive live delivery event alerts in your own system, and share secure tracking links with customers. Under the hood, this is powered by a versioned JSON API.

• Push delivery tasks in bulk from OMS/ERP systems.
• Let B2B clients push their own deliveries with a per-client API key.
• Receive route-started, upcoming, completed, and failed delivery alerts in your admin system.
• Offer customer tracking links without exposing staff credentials.
• Optionally enable direct customer email updates when messaging is configured.

Partner integration endpoints

These are the routes most teams wire first: delivery-task push endpoints under a single X-API-Key (including channel adapters), plus B2B shipper push and a read-only public tracking call for custom recipient experiences.

Paths are relative to {YOUR_API_HOST}/api/v1.

Available integrations

Start from a business integration page first, then open technical setup details only when your operations and engineering teams are ready to implement.

Integrations API reference

ReDoc at /redoc documents partner-facing endpoints: delivery-task push, channel adapters, B2B shipper-client push, and public customer tracking. It does not list dispatch, routing, drivers, client portal login, or other staff-only APIs.

Circle Routes operators: full internal API is at /docs on the API host (Swagger, staff sign-in).

Authentication

Circle Routes supports two common patterns, depending on whether a person or a system is calling the API.

Delivery event alerts (webhooks)

Circle Routes can notify your admin system whenever important delivery milestones happen. Your platform stays in sync in near real time and can decide how to notify customers (email, WhatsApp, or internal workflows).

Webhook authentication

• Method: POST
• Headers: Content-Type: application/json
• Headers: X-API-Key: <your-configured-key>
• Headers: User-Agent: Circle Routes/1.0

Each alert includes order, customer, and route context so your downstream systems can automate follow-up actions. For payload details and headers, refer to the internal document docs/ADMIN_SYSTEM_INTEGRATION.md.

Bulk push

POST {YOUR_API_HOST}/api/v1/delivery-tasks/push — push batches of stops in JSON. Behaviour matches the spreadsheet import your planners already trust, including time-window parsing from delivery_time when paired with delivery_date.

Request

• Content-Type: application/json
• X-API-Key as described above
• Body: a JSON array of task objects (same fields as the Excel import).

Required fields

Each object must include customer_name. The importer also requires a valid delivery_date on every row — it must be today or a future date in the server's calendar. Other columns (address, coordinates, tracking ID, delivery_time, package counts, and more) follow the same field names as your Excel template; unknown keys are ignored after validation.

Task type (optional)

Send task_type as delivery (default when omitted) or collection. Push/import collections are standalone only — same-visit collections are created from the driver app after a successful delivery. Collections do not receive AWBs, public tracking links, or customer messaging. Spreadsheet column: Task Type. Full field table: docs/DELIVERY_TASKS_PUSH_API.md.

B2B client tagging (optional)

When you push deliveries for multiple B2B clients through the operator X-API-Key, tag each task with either:

• shipper_client — string matching the client's Import column value, portal slug, or name (same as the spreadsheet Shipper Client column)
• shipper_client_id — numeric internal ID if you already store it

Unknown shipper_client values are skipped with a warning; the task is still imported untagged. Configure clients under Settings → Client portals.

Successful response

200 OK with a summary object: total_rows, imported_rows, failed_rows, delivery_dates, and optional errors (per-row messages). Partial success still returns 200 — always inspect failed_rows and errors.

Example

curl -X POST "{YOUR_API_HOST}/api/v1/delivery-tasks/push" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SECRET_KEY" \
  -d '[
    {
      "customer_name": "Jane Doe",
      "phone_no": "971501234567",
      "address": "123 Main St, Dubai",
      "city_name": "Dubai",
      "delivery_date": "2025-02-21",
      "delivery_time": "Evening 7pm - 9pm",
      "order_id": 1001,
      "awb": "HLC-0000779942",
      "shipper_client": "Acme Retail",
      "no_of_delivery_boxes": 2
    },
    {
      "customer_name": "Return Desk",
      "phone_no": "971501111111",
      "address": "Warehouse inbound",
      "city_name": "Dubai",
      "delivery_date": "2025-02-21",
      "task_type": "collection",
      "collected_items_count": 2
    }
  ]'

Cancel, delete & export

The same API key can maintain parity when orders are cancelled in your source system, and can export raw rows for BI or SLA reporting.

Cancel or delete — request body

Send exactly one lookup strategy: task_id, awb, or order_id. Optional reason is stored when the action is a cancellation on an in-progress route.

By task id

{
  "task_id": 12345,
  "reason": "Cancelled in OMS"
}

By tracking ID

{
  "awb": "HLC-0000779942"
}

By order id + delivery id

{
  "order_id": 1001
}

Cancel or delete — example

curl -X POST "{YOUR_API_HOST}/api/v1/delivery-tasks/push/cancel-or-delete" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SECRET_KEY" \
  -d '{"task_id":12345,"reason":"Cancelled in OMS"}'

Success returns 200 with action either deleted or cancelled, plus task_id and was_assigned.

Export — query parameters

Optional filters: delivery_date_from, delivery_date_to (YYYY-MM-DD), status, pagination skip (default 0), limit (default 500, max 2000). Response shape: total, skip, limit, items (array of task snapshots for KPI use).

Export — example

curl -X GET "{YOUR_API_HOST}/api/v1/delivery-tasks/push/export?delivery_date_from=2025-02-01&delivery_date_to=2025-02-29&skip=0&limit=500" \
  -H "X-API-Key: YOUR_SECRET_KEY"

Reschedule one task

POST {YOUR_API_HOST}/api/v1/delivery-tasks/push/reschedule — same X-API-Key as push. Use when the delivery date or service window changes in your source system. Provide the same identifier rules as cancel/delete, and at least one of delivery_date, complete_after, or complete_before. Completed or delivered tasks are rejected with 400.

Example bodies

New delivery date (by tracking ID)

{
  "awb": "HLC-0000779942",
  "delivery_date": "2025-02-25T00:00:00"
}

Explicit window (by task id)

{
  "task_id": 12345,
  "complete_after": "2025-02-21T19:00:00",
  "complete_before": "2025-02-21T21:00:00"
}

Example request

curl -X POST "{YOUR_API_HOST}/api/v1/delivery-tasks/push/reschedule" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SECRET_KEY" \
  -d '{"awb":"HLC-0000779942","delivery_date":"2025-02-25T00:00:00"}'

Success 200 returns message, task_id, route_status, and smart_reoptimized (whether an in-progress route was queued for smart re-optimization).

B2B client push

POST {YOUR_API_HOST}/api/v1/shipper-clients/push/deliveries — lets a B2B client push delivery tasks from their OMS. Uses the same JSON task shape as bulk push, but each request is automatically tagged to the client that owns the API key.

Authentication

• Header: X-Shipper-API-Key: <key-from-client-portals-settings>
• Generate the key in Circle Routes under Settings → Client portals → Generate push key.
• Missing or invalid keys return 401.

Request body

JSON array of delivery task objects — same fields as POST /delivery-tasks/push (customer name, phone, address, delivery date, time window, order id, etc.). Do not send shipper_client or shipper_client_id; scoping is implicit from the API key.

Example request

curl -X POST "{YOUR_API_HOST}/api/v1/shipper-clients/push/deliveries" \
  -H "Content-Type: application/json" \
  -H "X-Shipper-API-Key: shp_your_client_key_here" \
  -d '[{
    "customer_name": "Jane Doe",
    "phone_no": "971501234567",
    "address": "Villa 12, Al Barsha, Dubai",
    "delivery_date": "2026-07-22T00:00:00",
    "delivery_time": "06:00 - 14:00",
    "order_id": 10001
  }]'

Success returns the same upload summary as bulk push (imported_rows, failed_rows, optional errors). See the Shipper clients section in ReDoc for the live schema.

Customer tracking (public)

Recipients open a tracking link in the browser. If you are building a custom experience, you can read the same payload programmatically — no API key or login required; the opaque token is the credential.

Returns structured tracking data while the link is active and not expired. Inactive or expired links return410; unknown tokens return 404.

Response shape (JSON)

Top-level keys match the public contract: stop (the recipient's stop, nested status and delivery_task summary), route (route metadata and ordered stops), optional live driver_location and eta, is_active, expires_at, and optional survey_status. Field-by-field types and examples are in /docs on your API host under the public tracking schema.

Customer updates

Customers can always be updated through secure tracking links. If you want Circle Routes to send notifications directly, optional email notifications are supported when operator messaging is enabled and configured.

• Tracking links work without a staff login and can power your customer-facing experience.
• Direct email delivery uses Brevo when email messaging is enabled.
• You can keep full control in your own admin stack by using webhook alerts instead.

Staff, dispatch & driver APIs

Beyond the push feed, Circle Routes exposes many routes used by the web planner, dispatch console, dashboards, and driver clients — for example routes, stops, assignments, dispatch boards, insights, and configuration. Those endpoints expect a valid Bearer token and the same role rules as the product UI.

For partner engineering, treat OpenAPI as the contract: generate clients, mock servers, or contract tests from the published schema, and validate each flow in a test environment before going live.

Errors & status codes

Cancel, delete, and reschedule also return 400 for validation, delivered tasks, or route-state conflicts — error bodies are JSON with a detail string; exact shapes are listed in OpenAPI.