HelloRoute integration reference

Overview

HelloRoute 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 REST JSON API.

• Push delivery tasks in bulk from OMS/ERP systems.
• 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 SMS/email updates when messaging is configured.

Partner integration endpoints

These are the routes most teams wire first: four under a single X-API-Key (see below), plus 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 only the endpoints in the table above (push, export, channel adapters, and public tracking). It does not list dispatch, routing, drivers, or other staff-only APIs.

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

Authentication

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

Delivery event alerts (webhooks)

HelloRoute 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 (SMS, email, push, or internal workflows).

Webhook authentication

• Method: POST
• Headers: Content-Type: application/json
• Headers: X-API-Key: <your-configured-key>
• Headers: User-Agent: HelloRoute/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, AWB, delivery_time, box counts, and more) follow the same field names as your Excel template; unknown keys are ignored after validation.

Successful response

200 OK with a summary object: total_rows, imported_rows, failed_rows, 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",
      "no_of_delivery_boxes": 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, or awb, or both order_id and delivery_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 AWB

{
  "awb": "HLC-0000779942"
}

By order id + delivery id

{
  "order_id": 1001,
  "delivery_id": 2001
}

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 AWB)

{
  "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).

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 HelloRoute to send notifications directly, optional SMS and email channels are supported when operator messaging is enabled and configured.

• Tracking links work without a staff login and can power your customer-facing experience.
• Direct SMS delivery uses Twilio when SMS messaging is enabled.
• Direct email delivery uses Resend 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, HelloRoute 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 staging tenant before production traffic.

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.