Migrating

Already on BATS?

If you already send leads to BATS, you can send the same payload to RouteDesk. Change two things: the URL and the Auth Key.

Switching over

Point the request at RouteDesk. Send it to:

POSThttps://api.routedesk.com/api/v1/public/leads

Use the broker's RouteDesk Auth Key. Put it in the AuthKey field of the body, where you send it today, or in an Authorization: Bearer header. See Authentication.
Send a test lead and have the broker check it, as described in Testing your integration.

Everything else stays the same: field names, the capital V in Vehicles, numeric transport types and MM/DD/YYYY dates. Responses follow Responses and errors.

curl https://api.routedesk.com/api/v1/public/leads \
  -H "Authorization: Bearer YOUR_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
      }
    ]
  }'

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({
    "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
      }
    ]
  }),
});

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

<?php

$payload = [
    '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,
        ],
    ],
];

$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={
        "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,
            },
        ],
    },
    timeout=10,
)

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

Fields

first_namestring, up to 100 charactersOptional

The customer's first name.

last_namestring, 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. Send phone, email, or both. A lead with neither is rejected.

origin_citystring, up to 100 charactersRequired

City of the pickup location.

origin_statestring, up to 50 charactersRequired

State or province of the pickup location.

origin_postal_codestring, up to 20 charactersOptional

ZIP or postal code of the pickup location.

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

destination_citystring, up to 100 charactersRequired

City of the delivery location.

destination_statestring, up to 50 charactersRequired

State or province of the delivery location.

destination_postal_codestring, up to 20 charactersOptional

ZIP or postal code of the delivery location.

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

ship_datestring, up to 30 charactersOptional

MM/DD/YYYY (month first) or YYYY-MM-DD. Anything else is ignored and the lead is saved as "first available".

transport_typenumber or stringOptional

1 for open, 2 for enclosed. The words open and enclosed also work. Anything else is saved as open.

Vehiclesarray of objectsRequired

The vehicles to ship. At least one. Note the capital V.

vehicle_makestring, up to 50 charactersRequired: For example Toyota.
vehicle_modelstring, up to 50 charactersRequired: For example Camry.
vehicle_model_yearnumber 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.
vehicle_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.
vehicle_inop0, 1 or booleanOptional: 1 or true if the vehicle does not run.

How it differs from the standard format

The legacy format is forgiving so that existing integrations keep working. Where the standard format rejects a value, the legacy format usually accepts the lead and drops or replaces the value:

An unrecognized transport_type is saved as open. The standard format rejects it.
An unrecognized ship_date is ignored and the lead is saved as "first available". The standard format rejects it.
There is no notes field. To pass on what the customer told you, use the standard format and its notes field.

How the format is chosen

RouteDesk reads a request as the standard format when its body has an origin object or a lowercase vehicles list. Anything else is read as the legacy format.

Do not mix the two. A legacy request with one standard-format field, such as a lowercase vehicles, is read as the standard format and rejected with errors about fields you never meant to send.