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:
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.
{
"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
You will need to contact us to obtain an account_id and access_token in order to be able to post leads.
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.
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.