Introduction

Chariot provides an external-facing API for creating new leads. It is a single endpoint described in this document below. If you are considering connecting with Chariot via this API, please read the documentation and contact us directly if you need an access token or want to set up a test connection.

Things You’ll Need to Obtain from Chariot

To access and use the API, you’ll need to request the following from Chariot: To generate these credentials via UI, follow these steps:

Log in to your Chariot account.
Navigate to: Users > Office Users > API Users.
Click +Create API User to create a new Account ID and Auth Token.

account_id: Unique identifier for your account.
auth_token: A secure token required for API authentication.
Chariot URL

API

The API is exposed via the api/external/lead endpoint. So the full URL will be something like https://{client_name}.chariotmove.com/api/external/lead</ to which you would make a POST request with contents described below. Fields with ! are required, everything else is optional. You will get a 200 response only if the lead was created successfully, and a 4xx error with a descriptive error message otherwise. Ensure you include the Content-Type: application/json header in your POST request.

{
   "meta": !{
     "account_id": !string,
     "auth_token": !string
   },
   "customer": !{
       "first_name": !string,
       "last_name": !string,
       "phone" !string,
       "email" !string,
       "category": ! "RESIDENTIAL" | "COMMERCIAL",
       "company_name": string
   },
   "other_contacts": [
       {
           "first_name": !string,
           "last_name": !string,
           "phone": string,
           "email": string
       }
   ],
   "lead": !{
       "lead_source": string,
       "other_source": string,
       "date_requested": ISO date string,
       "date_flexibility": "EXACT" | "PLUS_ONE" | "MINUS_ONE" | "PLUS_MINUS_ONE" | "PLUS_MINUS_TWO" | "PLUS_MINUS_THREE",
       "job_services": {
           "moving": "FULL_MOVE" | "LOAD_ONLY" | "UNLOAD_ONLY" | "MOVE_WITHIN_SAME_BUILDING" | "DELIVERY" | "NONE",
           "packing": "FULL_PACKING" | "FULL_PACKING_UNPACKING" | "PARTIAL_PACKING" | "PARTIAL_PACKING_UNPACKING" | "NONE",
           "storage": "STORAGE_IN" | "STORAGE_OUT" | "NONE"
       }
   },
   "job": {
       "distance_category": "IN_STATE_SHORT" | "IN_STATE_LONG" | "INTERSTATE",
       "notes": string
   },
   "locations": [
       {
           "raw_address": !string,
           "apartment_number": string,
           "category": "STUDIO" | "ONE_BEDROOM" | "TWO_BEDROOM" | "THREE_PLUS_BEDROOM" | "HOUSE" | "CONDO" | "TOWNHOME" | "COMMERCIAL" | "STORAGE_UNIT" | "WAREHOUSE",
           "floor": string,
           "parking": "STREET" | "GARAGE" | "PARKING_LOT" | "DRIVEWAY"| "ALLEY" | "LOADING_DOCK" | "OTHER" | "UNKNOWN",
           "access": "ELEVATOR_NO_STAIRS", "BASEMENT", "GROUND_FLOOR", "ONE_FLIGHT", "TWO_FLIGHTS", "THREE_FLIGHTS", "FOUR_FLIGHTS", "FIVE_FLIGHTS", "SIX_PLUS_FLIGHTS",
           "stories": string,
           "to_door_distance": "UNDER_FIFTY" | "FIFTY_ONE_TO_ONE_HUNDRED" | "ONE_HUNDRED_ONE_TO_TWO_HUNDRED" | "OVER_TWO_HUNDRED_ONE" | "UNKNOWN",
           "purpose": "PICK_UP" | "DROP_OFF",
           "coi_required": "YES" | "NO" | "IDK",
           "notes": string
       }
   ],
   "inventory": {
       "inventory_items": [
           {
               "name": !string,
               "room": string,
               "quantity" !int,
               "not_moving_quantity": !int,
               "volume": decimal,
               "weight": decimal,
               "packing_type": "PBO" | "CP",
               "notes": string
           }
       ],
       "notes": string
   }
}

Examples

Here are a couple of examples of valid payloads:

Minimal payload

{
   "meta": {"account_id": "test_user", "auth_token": "XXXX"},
   "customer": {
       "first_name": "John",
       "last_name": "",
       "phone": "7325551212",
       "email": "john@example.com",
       "category": "",
   },
}

Simple payload

{
   "meta": {"account_id": "test_user", "auth_token": "XXXX"},
   "customer": {
       "first_name": "Fobby",
       "last_name": "Doy",
       "phone": "7325551212",
       "email": "fobby@example.com",
       "category": "RESIDENTIAL",
   },
   "locations": [
       {"raw_address": "1216 Broadway New York NY 10000", "floor": "4"},
   ],
   "other_contacts": [],
   "lead": {"job_services": {"moving": "LOAD_ONLY"}},
   "job": {},
   "inventory": {
       "inventory_items": [],
       "notes": "some inventory notes",
   },
}

Maximal payload

{
   "meta": {"account_id": "test_user", "auth_token": "XXXX"},
   "customer": {
       "first_name": "Dobby",
       "last_name": "Boyd",
       "phone": "7325551212",
       "email": "dobby@example.com",
       "category": "COMMERCIAL",
       "company_name": "Acme",
   },
   "locations": [
       {"raw_address": "506 washington ave linden nj", "floor": 3},
       {"raw_address": "716 amherst road linden nj", "floor": 1},
       {
           "raw_address": "400 n wood ave linden nj",
           "apartment_number": "A",
           "category": "THREE_PLUS_BEDROOM",
           "floor": "3",
           "parking": "LOADING_DOCK",
           "access": "SIX_PLUS_FLIGHTS",
           "stories": "several, it's a multiplex penthouse!",
           "to_door_distance": "ONE_HUNDRED_ONE_TO_TWO_HUNDRED",
           "purpose": "DROP_OFF",
           "coi_required": "IDK",
           "notes": "blablabla, blabla.",
       },
       {"raw_address": "1216 Broadway, New York NY 1000", "floor": 4},
       {"raw_address": "506 washington ave linden nj", "floor": 3},
   ],
   "other_contacts": [
       {
           "first_name": "",
           "last_name": "LastNameOnly",
           "phone": "8665551212",
           "email": "another@example.com",
       },
       {
           "first_name": "FirstNameOnly and no phone",
           "last_name": "",
           "email": "andanotherone@example.com",
       },
   ],
   "lead": {
       "lead_source": "some_source",
       "date_requested": "2023-03-01",
       "date_flexibility": "PLUS_MINUS_THREE",
       "job_services": {
           "moving": "LOAD_ONLY",
           "packing": "PARTIAL_PACKING_UNPACKING",
           "storage": "STORAGE_IN",
       },
   },
   "job": {
       "distance_category": "INTERSTATE",
       "notes": "Lorem Ipsum, etc.",
   },
   "inventory": {
       "inventory_items": [
           {
               "name": "Magazine Rack",
               "room": "Living Room",
               "quantity": 1,
               "not_moving_quantity": 0,
               "volume": "2.00",
               "weight": "14.00",
           },
           {
               "name": "Piano - Upright",
               "room": "Living Room",
               "quantity": 1,
               "not_moving_quantity": 0,
               "volume": "70.00",
               "weight": "490.00",
           },
           {
               "name": "Mysterious Goo",
               "room": "Green Room",
               "quantity": 1,
               "not_moving_quantity": 0,
               "volume": "69.00",
               "weight": "420.00",
           },
       ],
       "notes": "minimal inventory notes",
   },
}

Credentials, Testing, and Limits

To authenticate your requests, obtain credentials as follows:

Log in to your Chariot account.
Navigate to: Users > Office Users > API Users.
Click +Create API User. Your account ID and authentication token will be generated automatically.

We have a demo environment that you can use to test your connection, let us know if you would like that set up as well. Otherwise, once ready we can provide you with the above-mentioned credentials via phone or secure email. Before deploying, test integration as follows:

Prepare a sample JSON payload.
Use a tool like curl or a development framework to POST data to the API endpoint.
Verify the lead appears in your Chariot UI under Leads > Form Submitted.
Address errors in payload structure or authentication.

The API will allow you to make up to 6 requests per minute per user. If you go beyond that limit, you will get a 429 status code which you can use for any back-off logic.

Best Practices for API Usage

Keep Credentials Secure: Never publish or hardcode your API credentials in public repositories.
Test Thoroughly: Use a testing or development environment to validate your integration before production deployment.
Monitor Submission Logs: Regularly review logs to identify and debug integration issues promptly.
Stay Within Rate Limits: Implement back-off logic to handle 429 status codes effectively.

Connecting Jotform Leads to Chariot

Integrating Chariot with External Lead Providers via API