Quickstart - Superior Van Partner API

Follow these steps to authenticate with Superior Van & Mobility and send your first lead.

Request your API key

Ask your Superior Van partner contact for an API key. Send it on every request in the x-api-key header.

Set your environment

Work in sandbox first:

# Set environment variables for your tooling
export SUPERIORVAN_API_KEY="<your-api-key>"
export SUPERIORVAN_BASE_URL="https://sandbox.superiorvan.com/v1"

Use https://api.superiorvan.com/v1 when you are ready for production.

Create your first lead

curl -X POST "$SUPERIORVAN_BASE_URL/lead" \
  -H "x-api-key: $SUPERIORVAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Rivers",
    "email": "alex.rivers@example.com",
    "phone": "502-555-1234",
    "zip": "40202",
    "deal_type": "sales",
    "vendor_name": "ABC Vendor",
    "lead_notes": "Customer interested in a new van. Follow up next week.",
    "external_lead_id": "VENDOR-12345",
    "vehicle_year": "2025",
    "vehicle_make": "Toyota",
    "vehicle_model": "Sienna",
    "vehicle_miles": "12000"
  }'

The response includes a leadId inside body.leadId.

Check lead status

Use the returned leadId to check status updates.

curl -X GET "$SUPERIORVAN_BASE_URL/lead/61364584065" \
  -H "x-api-key: $SUPERIORVAN_API_KEY"

Possible status values are In Progress, Quoted, Evaluation Scheduled, Won, and Lost.

Required headers

x-api-key: <your-api-key> is required on every request.
Content-Type: application/json is required when creating a lead.

Required create lead fields

A POST /lead request must include:

first_name
deal_type
vendor_name
lead_notes
email OR phone

last_name and zip are optional. email and phone are conditionally required, so the request may include only email, only phone, or both. Phone numbers may be formatted with spaces, hyphens, parentheses, or a leading +1. The API accepts phone numbers that contain 10 digits, or 11 digits starting with 1.

Status codes to expect

The API response includes a statusCode field in the JSON response.

200 for success.
400 for validation errors.
403 for missing or invalid API keys.
404 when a referenced lead cannot be found.
5xx for unexpected server errors.

Next, review the API Reference for schemas, required fields, and additional examples.

​Required headers

​Required create lead fields

​Status codes to expect

Required headers

Required create lead fields

Status codes to expect