Get started

Authentication

Every request carries an Auth Key. The key tells RouteDesk which broker the lead is for and which of their lead sources it came from.

The Auth Key

A broker creates one lead source in RouteDesk for each vendor they buy leads from. Each lead source has its own Auth Key, a long string starting with lsk_.

The broker copies the key from Settings → Lead sources and sends it to you. RouteDesk shows a key only once, when it is created, so if it is lost the broker generates a new one.

Working with several brokers? Each one gives you their own key. The key alone decides which account a lead lands in.

Sending the key

Send the key in one of two places:

The Authorization header, as Bearer YOUR_AUTH_KEY. Use this for a new integration.
An AuthKey field at the top level of the JSON body. This is how the legacy format usually sends it, and it works with both formats.

If you send both, the key in the body is used.

Header (recommended)

curl https://api.routedesk.com/api/v1/public/leads \
  -H "Authorization: Bearer YOUR_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+13055550142","origin":{"city":"Miami","state":"FL"},"destination":{"city":"Dallas","state":"TX"},"vehicles":[{"make":"Toyota","model":"Camry"}]}'

In the body

curl https://api.routedesk.com/api/v1/public/leads \
  -H "Content-Type: application/json" \
  -d '{"AuthKey":"YOUR_AUTH_KEY","phone":"+13055550142","origin":{"city":"Miami","state":"FL"},"destination":{"city":"Dallas","state":"TX"},"vehicles":[{"make":"Toyota","model":"Camry"}]}'

Keeping the key safe

Keep the key on your server and send requests from there, over HTTPS.
Never put it in a web page, a mobile app, a URL, or a public code repository.
If a key may have leaked, ask the broker to regenerate it. The old key stops working the moment they do, so switch to the new one straight away.

A broker can also switch a lead source off. Your key then gets 403 until they switch it back on.

Authentication errors

401Auth Key is required
No Auth Key was found in the Authorization header or the body. Send the header as exactly Authorization: Bearer <key>.
401Invalid Auth Key
The key does not exist. It may have a typo, or the broker regenerated it. Ask the broker for the current key.
403Lead source is inactive
The key is right, but the broker has switched this lead source off. Stop sending and contact the broker.

These requests create nothing and do not appear in the broker's list of submissions. The full list of responses is in Responses and errors.