Lead intake API

Create a lead

Send one lead per request. This page covers the standard format; the legacy format has its own page.

The request

POST/api/v1/public/leads

Send to https://api.routedesk.com over HTTPS.
Set Content-Type: application/json and send the lead as a JSON object.
Authenticate with your Auth Key, as described in Authentication.
One lead per request. There is no batch endpoint.

A 201 response carries the new lead's leadId. The example beside this text uses every field the standard format accepts.

curl https://api.routedesk.com/api/v1/public/leads \
  -H "Authorization: Bearer YOUR_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+13055550142",
    "origin": {
      "city": "Miami",
      "state": "FL",
      "postalCode": "33101",
      "country": "US"
    },
    "destination": {
      "city": "Toronto",
      "state": "ON",
      "postalCode": "M5V 2T6",
      "country": "CA"
    },
    "shipDate": "2026-12-01",
    "transportType": "ENCLOSED",
    "notes": "Second vehicle is a project car and does not start.",
    "vehicles": [
      {
        "make": "Toyota",
        "model": "Camry",
        "modelYear": 2022,
        "type": "CAR",
        "inoperable": false
      },
      {
        "make": "Ford",
        "model": "Bronco",
        "modelYear": 1972,
        "type": "SUV",
        "inoperable": true
      }
    ]
  }'

const response = await fetch('https://api.routedesk.com/api/v1/public/leads', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_AUTH_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+13055550142",
    "origin": {
      "city": "Miami",
      "state": "FL",
      "postalCode": "33101",
      "country": "US"
    },
    "destination": {
      "city": "Toronto",
      "state": "ON",
      "postalCode": "M5V 2T6",
      "country": "CA"
    },
    "shipDate": "2026-12-01",
    "transportType": "ENCLOSED",
    "notes": "Second vehicle is a project car and does not start.",
    "vehicles": [
      {
        "make": "Toyota",
        "model": "Camry",
        "modelYear": 2022,
        "type": "CAR",
        "inoperable": false
      },
      {
        "make": "Ford",
        "model": "Bronco",
        "modelYear": 1972,
        "type": "SUV",
        "inoperable": true
      }
    ]
  }),
});

const result = await response.json();
console.log(response.status, result);

<?php

$payload = [
    'firstName' => 'Jordan',
    'lastName' => 'Rivera',
    'email' => 'jordan.rivera@example.com',
    'phone' => '+13055550142',
    'origin' => [
        'city' => 'Miami',
        'state' => 'FL',
        'postalCode' => '33101',
        'country' => 'US',
    ],
    'destination' => [
        'city' => 'Toronto',
        'state' => 'ON',
        'postalCode' => 'M5V 2T6',
        'country' => 'CA',
    ],
    'shipDate' => '2026-12-01',
    'transportType' => 'ENCLOSED',
    'notes' => 'Second vehicle is a project car and does not start.',
    'vehicles' => [
        [
            'make' => 'Toyota',
            'model' => 'Camry',
            'modelYear' => 2022,
            'type' => 'CAR',
            'inoperable' => false,
        ],
        [
            'make' => 'Ford',
            'model' => 'Bronco',
            'modelYear' => 1972,
            'type' => 'SUV',
            'inoperable' => true,
        ],
    ],
];

$ch = curl_init('https://api.routedesk.com/api/v1/public/leads');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_AUTH_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, ' ', $body;

import requests

response = requests.post(
    "https://api.routedesk.com/api/v1/public/leads",
    headers={"Authorization": "Bearer YOUR_AUTH_KEY"},
    json={
        "firstName": "Jordan",
        "lastName": "Rivera",
        "email": "jordan.rivera@example.com",
        "phone": "+13055550142",
        "origin": {
            "city": "Miami",
            "state": "FL",
            "postalCode": "33101",
            "country": "US",
        },
        "destination": {
            "city": "Toronto",
            "state": "ON",
            "postalCode": "M5V 2T6",
            "country": "CA",
        },
        "shipDate": "2026-12-01",
        "transportType": "ENCLOSED",
        "notes": "Second vehicle is a project car and does not start.",
        "vehicles": [
            {
                "make": "Toyota",
                "model": "Camry",
                "modelYear": 2022,
                "type": "CAR",
                "inoperable": False,
            },
            {
                "make": "Ford",
                "model": "Bronco",
                "modelYear": 1972,
                "type": "SUV",
                "inoperable": True,
            },
        ],
    },
    timeout=10,
)

print(response.status_code, response.json())

Response · 201

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

The minimum request

A lead needs:

a pickup and a delivery location, each with a city and a state;
at least one vehicle, with a make and a model;
a way to reach the customer: a phone, an email, or both.

Everything else is optional, but the more you send, the faster the broker can quote.

Minimum body

{
  "phone": "+13055550142",
  "origin": {
    "city": "Miami",
    "state": "FL"
  },
  "destination": {
    "city": "Dallas",
    "state": "TX"
  },
  "vehicles": [
    {
      "make": "Toyota",
      "model": "Camry"
    }
  ]
}

Fields

Fields marked Required must always be present. Length limits are enforced: a longer value is rejected with 422, not cut short.

firstNamestring, up to 100 charactersOptional

The customer's first name.

lastNamestring, up to 100 charactersOptional

The customer's last name.

emailstring, up to 320 charactersOptional

The customer's email address. Must be a valid address. Send phone, email, or both. A lead with neither is rejected.

phonestring, up to 40 charactersOptional

The customer's phone number, in any format. E.164 (+13055550142) is best. Send phone, email, or both. A lead with neither is rejected.

originobjectRequired

Where the vehicle is picked up.

citystring, up to 100 charactersRequired: City name.
statestring, up to 50 charactersRequired: State or province, ideally the two-letter code (FL, ON).
postalCodestring, up to 20 charactersOptional: ZIP or postal code.
countrystring, up to 40 charactersOptional: 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.

destinationobjectRequired

Where the vehicle is delivered.

citystring, up to 100 charactersRequired: City name.
statestring, up to 50 charactersRequired: State or province, ideally the two-letter code (FL, ON).
postalCodestring, up to 20 charactersOptional: ZIP or postal code.
countrystring, up to 40 charactersOptional: 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.

shipDatestring, up to 30 charactersOptional

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".

transportTypestringOptional

OPEN or ENCLOSED, in any letter case. Anything else is rejected. Defaults to OPEN.

notesstring, up to 2000 charactersOptional

Anything the customer told you that does not fit another field. Shown to the broker.

vehiclesarray of objectsRequired

The vehicles to ship. At least one.

makestring, up to 50 charactersRequired: For example Toyota.
modelstring, up to 50 charactersRequired: For example Camry.
modelYearnumber or stringOptional: 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.
typestring, up to 50 charactersOptional: One of CAR, SUV, TRUCK, VAN, MOTORCYCLE, RV, ATV, BOAT, OTHER, in any letter case. Anything else, or no value, is saved as OTHER.
inoperablebooleanOptional: true if the vehicle does not run. Must be a boolean, not 1. Defaults to false.

Fields RouteDesk does not know

A field that is not listed above is ignored, and the lead is still created. That keeps a request working if you send extra data, but it also means a misspelled field name fails silently: firstname instead of firstName creates a lead with no first name.

The broker can see which field names were ignored on each submission, so they can spot a typo on their side too.