Lead intake API

Responses and errors

Check the HTTP status code first. It tells you whether the lead was created and whether sending again can help.

Status codes

Only 201 means a lead was created. Every other response means it was not.

201Created
The lead is in the broker’s account. Store the leadId if you want a reference. Do not send the lead again.
400Bad request
The body is not valid JSON, or is empty, while Content-Type says application/json. Fix how the body is built. Serialize it with your JSON library, not by hand.
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.
413Request body is too large
The body is over 256 KB. A normal lead is under 2 KB. Send one lead per request and drop fields RouteDesk does not use.
422Validation failed
The lead is missing a required field or a value is not accepted. Read errors: each key is a field, each value says what is wrong. Fix and resend.
429Rate limit exceeded
More than 120 requests in a minute from your IP address. Wait the number of seconds in the Retry-After header, then resend.
500Could not create the lead
Something failed on our side. The lead was not created. Retry with backoff. The broker sees the failure in their submissions list.

Response bodies

Responses come in two shapes.

201, 401, 403, 422 and 500 return a JSON object with a success flag and a message.
400, 413 and 429 are returned before the request is read as a lead. They use the standard Problem Details format, with Content-Type: application/problem+json, a title, a detail and a request_id.

Branch on the status code, not on the text of message or title, which may be reworded.

201 · Created

{
  "success": true,
  "message": "Lead created successfully",
  "leadId": "e763f6b3-946b-4980-83d6-859cbd636a98"
}

400 · Problem Details

{
  "type": "https://routedesk.com/errors/validation",
  "title": "Body is not valid JSON but content-type is set to 'application/json'",
  "status": 400,
  "detail": "Body is not valid JSON but content-type is set to 'application/json'",
  "instance": "/api/v1/public/leads",
  "request_id": "01a1d690-1a4c-74d6-9994-b633e772b591"
}

Reading a 422

A 422 lists what is wrong in errors. Each key is a top-level field and each value says what is wrong with it. You get one message per field, so fix them all and send the lead again.

A problem inside a nested object or a vehicle is reported on its parent. A vehicle with no make gives "vehicles": "make is required".
A missing phone and email is reported on phone.
If the body is not a JSON object at all, the error is under _. Sending JSON with a Content-Type other than application/json causes this.

The accepted values for every field are in Fields.

422 · Validation failed

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "origin": "Required",
    "shipDate": "shipDate must be ISO-8601 (YYYY-MM-DD)",
    "transportType": "transportType must be OPEN or ENCLOSED",
    "vehicles": "At least one vehicle is required"
  }
}