Your orders.
Your delivery workflow.

Dispatchr uses OAuth 2.0. For a server-to-server integration, exchange your credentials for an access token using the client_credentials grant.

Set CLIENT_ID and CLIENT_SECRET in your server environment, then request a token:

curl 'https://api.dispatchr.ai/v2/oauth/token' \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials'

Read access_token from the JSON response. Use it as a Bearer token in subsequent requests:

export ACCESS_TOKEN='YOUR_ACCESS_TOKEN'

A route describes what needs to move, where it starts, and where it ends. Send a pickup leg followed by a drop-off leg, along with your billing information.

Save the example below as route.json. Replace the example contacts and addresses, and set pickUpDateTime to your intended pickup time.

{
  "route": {
    "referenceId": "example-delivery-001",
    "deliveryCategory": "boxes",
    "vehicleType": "CAR",
    "pickUpDateTime": "2030-06-17T13:00:00Z",
    "legs": [
      {
        "type": "PICK_UP",
        "addresses": [
          {
            "name": "Warehouse team",
            "company": "Example warehouse",
            "address": "125 Summer St",
            "city": "Boston",
            "postalCode": "02110",
            "locality": "MA",
            "phone": "2025550100"
          }
        ]
      },
      {
        "type": "DROP_OFF",
        "addresses": [
          {
            "name": "Receiving team",
            "company": "Example store",
            "address": "4 S Market St",
            "city": "Boston",
            "postalCode": "02109",
            "locality": "MA",
            "phone": "2025550101"
          }
        ]
      }
    ]
  },
  "billing": {
    "tips": 0
  }
}

curl 'https://api.dispatchr.ai/v5/entity/route' \
  --request POST \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @route.json

A successful request returns 202 Accepted with the route. Keep its id to read, update, or cancel it later; set ROUTE_ID to that value for the examples below.

What your request needs

• Route details. A delivery category, vehicle type, and pickup time.
• Stops. 2–4 legs, with pickup first and drop-off last. Up to 50 addresses per leg and 100 stops per route.
• Billing. A billing object with non-negative tips. Confirm your production billing setup before creating live deliveries.

Optionally pass a top-level driverPool ID belonging to your account. If omitted, Dispatchr selects the first available driver pool, or uses 0 when there are none.

Plans change. Update a stop’s instructions or address while the route is active. First, fetch the route to get the current stops and their address uid values.

curl "https://api.dispatchr.ai/v3/entity/route/$ROUTE_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Save the complete updated leg list as update-route.json. Replace the placeholder UIDs with those from the route response and preserve existing stops you want to keep.

{
  "legs": [
    {
      "type": "PICK_UP",
      "addresses": [
        {
          "uid": "YOUR_PICKUP_ADDRESS_UID",
          "name": "Warehouse team",
          "company": "Example warehouse",
          "address": "125 Summer St",
          "city": "Boston",
          "postalCode": "02110",
          "locality": "MA",
          "phone": "2025550100"
        }
      ]
    },
    {
      "type": "DROP_OFF",
      "addresses": [
        {
          "uid": "YOUR_DROPOFF_ADDRESS_UID",
          "name": "Receiving team",
          "company": "Example store",
          "address": "4 S Market St",
          "city": "Boston",
          "postalCode": "02109",
          "locality": "MA",
          "phone": "2025550101",
          "instructions": "Use the loading entrance."
        }
      ]
    }
  ]
}

curl "https://api.dispatchr.ai/v4/entity/route/$ROUTE_ID" \
  --request PUT \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @update-route.json

API versions are specific to each operation: use v5 to create a route and v4 to update it.

To cancel a route, set its deliveryStatus to cancelled. The route must be in the created or accepted state.

curl "https://api.dispatchr.ai/v3/entity/route/$ROUTE_ID/status" \
  --request PUT \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"deliveryStatus":"cancelled"}'

Check the response before treating the route as cancelled. Requests for ineligible routes are rejected, and billing failures can prevent cancellation.

Use the test Account ID and Auth Token from your portal settings to request a test Bearer token. The API base URL stays the same; your credentials determine test mode. Billing setup is not required for test-mode calls.

1. Authenticate with test credentials.Keep your test and production credentials separate.
2. Create, read, update, and cancel a route.Use example contacts and a future pickup time. Check the status and response after each request.
3. Handle unsuccessful requests.Check HTTP status codes and error responses. Don’t assume an unsuccessful creation request is safe to retry blindly.
4. Switch to production when you’re ready.Confirm billing and driver-pool configuration, then obtain a token using production credentials.