{"openapi":"3.1.0","info":{"title":"RouteDesk Lead Intake API","version":"1.0.0","description":"Send leads into an auto transport broker's RouteDesk account. One lead per request. Full documentation for people and coding agents: https://developer.routedesk.com/llms-full.txt"},"externalDocs":{"description":"Developer documentation","url":"https://developer.routedesk.com"},"servers":[{"url":"https://api.routedesk.com"}],"security":[{"authKey":[]}],"components":{"securitySchemes":{"authKey":{"type":"http","scheme":"bearer","description":"The Auth Key of a lead source, from the broker (starts with `lsk_`). Send it as `Authorization: Bearer <key>` with a capital B. It can also be sent as an `AuthKey` field in the JSON body; if both are sent, the body wins."}},"schemas":{"StandardLead":{"type":"object","properties":{"firstName":{"type":"string","maxLength":100,"description":"The customer's first name."},"lastName":{"type":"string","maxLength":100,"description":"The customer's last name."},"email":{"type":"string","format":"email","maxLength":320,"description":"The customer's email address. Must be a valid address. Send `phone`, `email`, or both. A lead with neither is rejected."},"phone":{"type":"string","maxLength":40,"description":"The customer's phone number, in any format. E.164 (`+13055550142`) is best. Send `phone`, `email`, or both. A lead with neither is rejected."},"origin":{"type":"object","properties":{"city":{"type":"string","minLength":1,"maxLength":100,"description":"City name."},"state":{"type":"string","minLength":1,"maxLength":50,"description":"State or province, ideally the two-letter code (`FL`, `ON`)."},"postalCode":{"type":"string","maxLength":20,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":40,"description":"Two-letter ISO code such as `US` or `CA`. `USA`, `United States`, `Canada` and `Mexico` are also understood. If it is missing or not recognized, `US` is saved."}},"required":["city","state"],"description":"Where the vehicle is picked up."},"destination":{"type":"object","properties":{"city":{"type":"string","minLength":1,"maxLength":100,"description":"City name."},"state":{"type":"string","minLength":1,"maxLength":50,"description":"State or province, ideally the two-letter code (`FL`, `ON`)."},"postalCode":{"type":"string","maxLength":20,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":40,"description":"Two-letter ISO code such as `US` or `CA`. `USA`, `United States`, `Canada` and `Mexico` are also understood. If it is missing or not recognized, `US` is saved."}},"required":["city","state"],"description":"Where the vehicle is delivered."},"shipDate":{"type":"string","maxLength":30,"pattern":"^\\d{4}-\\d{2}-\\d{2}([T ].*)?$","description":"The date the customer wants to ship, as `YYYY-MM-DD`. A time after the date is allowed and ignored. Any other format is rejected. A date that does not exist, such as `2026-02-30`, is ignored. Without a usable date the lead is saved as \"first available\"."},"transportType":{"type":"string","maxLength":20,"description":"`OPEN` or `ENCLOSED`, in any letter case. Anything else is rejected. Defaults to `OPEN`.","enum":["OPEN","ENCLOSED"]},"notes":{"type":"string","maxLength":2000,"description":"Anything the customer told you that does not fit another field. Shown to the broker."},"vehicles":{"type":"array","items":{"type":"object","properties":{"make":{"type":"string","minLength":1,"maxLength":50,"description":"For example `Toyota`."},"model":{"type":"string","minLength":1,"maxLength":50,"description":"For example `Camry`."},"modelYear":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}],"description":"A number or a numeric string, such as `2022` or `\"2022\"`. If it is missing, or earlier than 1900, or more than two years in the future, the current year is saved."},"type":{"type":"string","maxLength":50,"description":"One of `CAR`, `SUV`, `TRUCK`, `VAN`, `MOTORCYCLE`, `RV`, `ATV`, `BOAT`, `OTHER`, in any letter case. Anything else, or no value, is saved as `OTHER`."},"inoperable":{"type":"boolean","description":"`true` if the vehicle does not run. Must be a boolean, not `1`. Defaults to `false`."}},"required":["make","model"]},"minItems":1,"description":"The vehicles to ship. At least one."}},"required":["origin","destination","vehicles"],"description":"Standard format. Send `phone`, `email`, or both: a request with neither is rejected with 422."},"LegacyLead":{"type":"object","properties":{"first_name":{"type":"string","maxLength":100,"description":"The customer's first name."},"last_name":{"type":"string","maxLength":100,"description":"The customer's last name."},"email":{"type":"string","format":"email","maxLength":320,"description":"The customer's email address. Must be a valid address. Send `phone`, `email`, or both. A lead with neither is rejected."},"phone":{"type":"string","maxLength":40,"description":"The customer's phone number, in any format. Send `phone`, `email`, or both. A lead with neither is rejected."},"origin_city":{"type":"string","minLength":1,"maxLength":100,"description":"City of the pickup location."},"origin_state":{"type":"string","minLength":1,"maxLength":50,"description":"State or province of the pickup location."},"origin_postal_code":{"type":"string","maxLength":20,"description":"ZIP or postal code of the pickup location."},"origin_country":{"type":"string","maxLength":40,"description":"Two-letter ISO code such as `US` or `CA`. `USA`, `United States`, `Canada` and `Mexico` are also understood. If it is missing or not recognized, `US` is saved."},"destination_city":{"type":"string","minLength":1,"maxLength":100,"description":"City of the delivery location."},"destination_state":{"type":"string","minLength":1,"maxLength":50,"description":"State or province of the delivery location."},"destination_postal_code":{"type":"string","maxLength":20,"description":"ZIP or postal code of the delivery location."},"destination_country":{"type":"string","maxLength":40,"description":"Two-letter ISO code such as `US` or `CA`. `USA`, `United States`, `Canada` and `Mexico` are also understood. If it is missing or not recognized, `US` is saved."},"ship_date":{"type":"string","maxLength":30,"description":"`MM/DD/YYYY` (month first) or `YYYY-MM-DD`. Anything else is ignored and the lead is saved as \"first available\"."},"transport_type":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}],"description":"`1` for open, `2` for enclosed. The words `open` and `enclosed` also work. Anything else is saved as open."},"Vehicles":{"type":"array","items":{"type":"object","properties":{"vehicle_inop":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]},{"type":"boolean"}],"description":"`1` or `true` if the vehicle does not run."},"vehicle_make":{"type":"string","minLength":1,"maxLength":50,"description":"For example `Toyota`."},"vehicle_model":{"type":"string","minLength":1,"maxLength":50,"description":"For example `Camry`."},"vehicle_model_year":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}],"description":"A number or a numeric string, such as `2022` or `\"2022\"`. If it is missing, or earlier than 1900, or more than two years in the future, the current year is saved."},"vehicle_type":{"type":"string","maxLength":50,"description":"One of `CAR`, `SUV`, `TRUCK`, `VAN`, `MOTORCYCLE`, `RV`, `ATV`, `BOAT`, `OTHER`, in any letter case. Anything else, or no value, is saved as `OTHER`."}},"required":["vehicle_make","vehicle_model"]},"minItems":1,"description":"The vehicles to ship. At least one. Note the capital `V`."}},"required":["origin_city","origin_state","destination_city","destination_state","Vehicles"],"description":"Legacy (BATS-style) format, for existing integrations. Send `phone`, `email`, or both. Use the standard format for new work."}}},"paths":{"/api/v1/public/leads":{"post":{"operationId":"createLead","summary":"Create a lead","description":"Creates one lead. Only `201` means a lead was created. There is no idempotency key: never resend a lead that got a response, and retry only `429` (after Retry-After) and `500` (with backoff). Limit: 120 requests per minute per IP; body limit 256 KB.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StandardLead"},{"$ref":"#/components/schemas/LegacyLead"}]},"examples":{"standard":{"summary":"Standard format","value":{"firstName":"Jordan","lastName":"Rivera","email":"jordan.rivera@example.com","phone":"+13055550142","origin":{"city":"Miami","state":"FL","postalCode":"33101"},"destination":{"city":"Dallas","state":"TX","postalCode":"75201"},"shipDate":"2026-12-01","transportType":"OPEN","vehicles":[{"make":"Toyota","model":"Camry","modelYear":2022}]}},"minimum":{"summary":"Smallest accepted lead","value":{"phone":"+13055550142","origin":{"city":"Miami","state":"FL"},"destination":{"city":"Dallas","state":"TX"},"vehicles":[{"make":"Toyota","model":"Camry"}]}},"legacy":{"summary":"Legacy (BATS-style) format","value":{"first_name":"Jordan","last_name":"Rivera","email":"jordan.rivera@example.com","phone":"(305) 555-0142","origin_city":"Miami","origin_state":"FL","origin_postal_code":"33101","origin_country":"USA","destination_city":"Dallas","destination_state":"TX","destination_postal_code":"75201","destination_country":"USA","ship_date":"12/01/2026","transport_type":1,"Vehicles":[{"vehicle_make":"Toyota","vehicle_model":"Camry","vehicle_model_year":"2022","vehicle_type":"Car","vehicle_inop":0}]}}}}}},"responses":{"201":{"description":"Created. The lead is in the broker’s account. Store the leadId if you want a reference. Do not send the lead again.","content":{"application/json":{"examples":{"Created":{"summary":"Created","value":{"success":true,"message":"Lead created successfully","leadId":"e763f6b3-946b-4980-83d6-859cbd636a98"}}}}}},"400":{"description":"Bad 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.","content":{"application/problem+json":{"examples":{"Bad_request":{"summary":"Bad request","value":{"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"}}}}}},"401":{"description":"Auth Key is required. No Auth Key was found in the Authorization header or the body. Send the header as exactly Authorization: Bearer <key>. Or: Invalid Auth Key. The key does not exist. It may have a typo, or the broker regenerated it.","content":{"application/json":{"examples":{"Auth_Key_is_required":{"summary":"Auth Key is required","value":{"success":false,"message":"Auth Key is required"}},"Invalid_Auth_Key":{"summary":"Invalid Auth Key","value":{"success":false,"message":"Invalid Auth Key"}}}}}},"403":{"description":"Lead source is inactive. The key is right, but the broker has switched this lead source off. Stop sending and contact the broker.","content":{"application/json":{"examples":{"Lead_source_is_inactive":{"summary":"Lead source is inactive","value":{"success":false,"message":"Lead source is inactive"}}}}}},"413":{"description":"Request 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.","content":{"application/problem+json":{"examples":{"Request_body_is_too_large":{"summary":"Request body is too large","value":{"type":"https://routedesk.com/errors/validation","title":"Request body is too large","status":413,"detail":"Request body is too large","instance":"/api/v1/public/leads","request_id":"01a1d690-1a7c-75ef-a9a4-5623631d89f7"}}}}}},"422":{"description":"Validation 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.","content":{"application/json":{"examples":{"Validation_failed":{"summary":"Validation failed","value":{"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"}}}}}}},"429":{"description":"Rate 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.","content":{"application/problem+json":{"examples":{"Rate_limit_exceeded":{"summary":"Rate limit exceeded","value":{"type":"https://routedesk.com/errors/rate-limited","title":"Rate Limit Exceeded","status":429,"detail":"Rate limit exceeded. Retry after 29 seconds.","retry_after":29,"instance":"/api/v1/public/leads","request_id":"01a1d690-946b-75fb-8fa2-6b6106b06cb5"}}}}}},"500":{"description":"Could 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.","content":{"application/json":{"examples":{"Could_not_create_the_lead":{"summary":"Could not create the lead","value":{"success":false,"message":"Could not create the lead"}}}}}}}}}}}