Create and dispatch a courier job with the API

1. Prepare your site

You need Node.js 22 or later, an API key with permission to create and dispatch jobs, and an existing customer, service type, two saved addresses, and driver from the same site. Use a courier service type that supports pickup and dropoff stops.

Create the key in Settings → API keys. Choose the appropriate role and store the key on your server. The example uses x-api-key; a key’s service account is subject to the API’s permissions.

Find customers, service types, and drivers with GET /customer/search, GET /servicetype/search, and GET /worker/search. Use the customer’s user ID for customer_user_id. Create saved addresses with POST /address and retain each returned data.id, or reuse address IDs from an existing job. Inspect the request and response fields in the API reference.

Confirm the driver’s availability and service requirements before assignment. Direct driver assignment needs a vehicle: configure the driver’s default vehicle or supply an assignable VEHICLE_ID. The driver availability example checks eligibility for an existing job.

2. Run the example

Download dispatch-job.mjs and review it before running. Set each value to a real record from your test site. You can omit VEHICLE_ID when the driver has a default vehicle.

export ROUTEIQ_BASE_URL="https://YOUR-SITE.routeiq.app/api"
export ROUTEIQ_API_KEY="YOUR-API-KEY"
export CUSTOMER_ID="CUSTOMER-USER-ID"
export SERVICE_TYPE_ID="SERVICE-TYPE-ID"
export PICKUP_ADDRESS_ID="PICKUP-ADDRESS-ID"
export DELIVERY_ADDRESS_ID="DELIVERY-ADDRESS-ID"
export DRIVER_ID="DRIVER-USER-ID"
# If the driver has no default vehicle:
# export VEHICLE_ID="VEHICLE-ID"

node dispatch-job.mjs

The example uses saved addresses, so no geocoding step is needed. It explicitly sets payment_method to cash; it does not charge a card. Adjust the payment method to your billing workflow before using it outside your test site.

3. Understand the three requests

1. POST /job creates two ordered stops: pickup and dropoff. It sends the customer user ID and service type ID as strings. Save the returned data.id.
2. POST /dispatch/assign assigns that job using job_id, driver_id, and optional vehicle_id. The example sets method to manual and require_confirmation to false.
3. GET /job/{id} reads back the job. The script prints its ID, assigned driver, and workflow state ID.

Creating a job and dispatching it are separate operations. Direct assignment does not require you to create a route first. See jobs, stops, and routes and the dispatch workflow guide for the operating model.

If your drivers must accept work first, use a supported confirmation or opt-in flow and verify that lifecycle separately. A successful assignment does not prove a driver accepted or completed a delivery.

4. Verify and recover

Open the returned job in the dashboard. Confirm the two stops are in order, the correct driver is assigned, and the workflow state matches your site’s configuration. State IDs are site-specific; do not hard-code another site’s IDs.

The script prints the created job ID before attempting dispatch and makes no automatic retries. If dispatch fails, keep that job and fix the assignment. Rerunning the whole script creates another job.

If creation times out before an ID is returned, search recent jobs and reconcile the order before retrying. If assignment times out, read the existing job to learn whether it succeeded. The example does not provide an idempotency key or guarantee exactly-once creation.

For ongoing status changes, follow Receive delivery updates with webhooks. Consult the backend’s live API reference for the complete request and response schemas.