API quickstart

The RouteOne REST API lets your own systems create orders, check rates and serviceability, fetch labels, track shipments and cancel shipments. It is meant for server-to-server use. Never call it from a browser or mobile app, because your key would be exposed. All requests and responses are JSON over HTTPS, and field names are snake_case.

Base URL

https://app.routeonex.com/api/public/v1

Create an API key

1. 1Open Settings and choose Configure API.
2. 2Click Generate New API Key.
3. 3Tick the Scopes the key needs (see the table below) and add a Description such as the name of the integration.
4. 4Click Generate Key.
5. 5Copy the key straight away. RouteOne stores only a hashed copy, so it is shown once. If you lose it, revoke it and generate a new one.

To stop a key working, click Revoke next to it. The same page contains the full API documentation with examples.

Scopes

Each key works only on the endpoints its scopes allow. Anything else returns 403.

Give each integration its own key with only the scopes it needs.

Authenticate

Send the full key, which looks like rok_xxxxxxxxxxxx.<secret> (the key ID, a dot, then the secret), as a Bearer token. Add Content-Type: application/json on POST requests.

Authorization: Bearer <keyId>.<secret>

Your first request

Check whether a pincode is serviceable (needs the serviceability:read scope):

curl "https://app.routeonex.com/api/public/v1/serviceability?pincode=560001" -H "Authorization: Bearer <keyId>.<secret>"

A successful reply looks like this:

{ "ok": true, "pincode": "560001", "city": "Bengaluru", "state": "Karnataka", "serviceable": true, "cod": true }

Responses and errors

Every response contains ok. Errors look like { "ok": false, "error": "weight_kg must be greater than 0" }.

Rate limit

Each key can make 120 requests per minute (a sliding window). Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get a 429 with a Retry-After header in seconds. Wait that long, then retry.