BATS accepts leads via HTTP POST protocol using JSON array as payload. Unique Authorization Code identifies the inbound payload to BATS Lead Receiving Engine, which then posts the lead to the appropriate Broker account in BATS.
This method is faster, encrypted, more secure, and more reliable than email delivery via email-to-parser-to-database method. BATS Lead Receiving Engine will send a reply to the sending system, informing it if the lead was successfully received or if any problems were encountered. This way the lead provider knows for sure if the lead was successfully delivered to the Broker. Additionally, BATS will not accept a lead if all the required information is not included in the lead. For example, if phone number is missing, BATS will not accept the lead. This way the Broker does not have to pay for leads that were incomplete.
How to set up a new lead source
Broker will create a new lead source in BATS for each Lead Provider and each website that will be sending leads to BATS. BATS will generate a new, unique Authorization Key (AuthKey) for each source. Broker can send an email containing the AuthKey directly from BATS to the programmer. These instructions are for the programmers who are setting up the HTTP POST communication from a Lead Provider or Broker's website to BATS.
Additional benefit of this setup is that the HTTP POST code needs to be set up only once, and all that needs to change is the AuthKey, which uniquely identifies the relationship between the lead source and the Broker account in BATS.
HTTP POST Instructions
After you have successfully tested your lead delivery against the Sandbox API you can start sending leads to the live delivery API endpoint at: https://api.batscrm.com/leads
Content Type: application/json
JSON Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {"AuthKey": {"type": "string"},
"Vehicles": {"items": {
"properties": {
"vehicle_inop": {"type": "integer"},
"vehicle_make": {"type": "string"},
"vehicle_model": {"type": "string"},
"vehicle_model_year": {"type": "integer"},
"vehicle_type": {"type": "string"}
"vehicle_width": {"type": "string"},
"vehicle_height": {"type": "string"},
"vehicle_length": {"type": "string"},
"vehicle_weight": {"type": "integer"},
"vehicle_weight_measure": {"type": "string"}
},
"type": "object"
},
"type": "array"},
"first_name": {"type": "string"},
"last_name": {"type": "string"},
"email": {"type": "string"},
"phone": {"type": "string"},
"ship_date": {"type": "string"},
"transport_type": {"type": "integer"},
"comment_from_shipper": {"type": "string"},
"origin_city": {"type": "string"},
"origin_country": {"type": "string"},
"origin_postal_code": {"type": "string"},
"origin_state": {"type": "string"},
"destination_city": {"type": "string"},
"destination_country": {"type": "string"},
"destination_postal_code": {"type": "string"},
"destination_state": {"type": "string"}
},
"required": ["AuthKey","first_name", "email","phone", "ship_date", "transport_type", "origin_postal_code", "destination_postal_code", "vehicle_make", "vehicle_model", "vehicle_model_year", "vehicle_inop"],
"type": "object"
}
Comments:
- Production AuthKey will be provided by BATS (for sandbox please use: 8c00130d-872f-4912-81c9-553f38ec61e0)
- vehicle_inop: 1 = Yes; 0 = No
- ship_date format: mm/dd/yyyy
- transport_type: 1 = Open; 2 = Enclosed; 3 = Driveaway
- vehicle_type: Accepted values are (these are case sensitive): Car, SUV, Pickup, Van, Motorcycle, Boat, Other
- Required fields, such as origin_postal_code can contain a dummy value if actual value is not available, but the field must contain value in the incoming JSON payload
- vehicle_weight_measure describes which weight measure is used for vehicle_weight. Allowed values are: lbs, kg, tons
API Response
Sandbox API will respond with a descriptive message in JSON format, explaining the validation results for each field. API will respond with code "422: Unprocessable Entity" if it finds any errors in the payload, otherwise it will respond with code 200. Sample response message looks like this:
{
"statusCode": "422",
"headers": {
"content-type": "application/json"
},
"body": "{
"AuthKey": "Valid",
"first_name": "Valid",
"last_name": "Last Name is not required but it was blank.",
"email": "Valid",
"phone": "Valid",
"ship_date": "Valid",
"transport_type": "Transport Type must have value of 1, 2, or 3.Transport Type is required.",
"origin_postal_code": "Valid",
"origin_city": "Valid",
"origin_state": "Valid",
"origin_country": "Valid",
"destination_postal_code": "Valid",
"destination_city": "Valid",
"destination_state": "Valid",
"destination_country": "Valid",
"Vehicles":[{
"vehicle_inop": "Vehicle Inop must have value of 0 or 1.Vehicle Inop field is required.",
"vehicle_type": "Valid",
"vehicle_make": "Vehicle Make is required.",
"vehicle_model": "Valid",
"vehicle_model_year": "Valid"
},{
"vehicle_inop": "Vehicle Inop must have value of 0 or 1.Vehicle Inop field is required.",
"vehicle_type": "Valid",
"vehicle_make": "Vehicle Make is required.",
"vehicle_model": "Valid",
"vehicle_model_year": "Valid"
}]}"
}
Example JSON Payload Messages:
Here you will find a few examples of payload messages that can be sent to BATS for lead delivery via HTTP POST.
You can use the following AuthKey for testing purposes. If the delivery was successful, upon receiving your payload BATS will respond with "OK, Lead :##", where ## will be the number that was assigned to the Lead in BATS.
If there was a problem with accepting the lead, BATS will respond with a descriptive message explaining the source of the problem.
Testing AuthKey: 8c00130d-872f-4912-81c9-553f38ec61e0
Simple One Vehicle Payload:
{
"AuthKey": "8c00130d-872f-4912-81c9-553f38ec61e0",
"first_name": "TIM",
"last_name": "DRESSLER",
"phone": "(972) 621-9999",
"comment_from_shipper": "asap please",
"origin_city": "Greenville",
"origin_state": "CA",
"origin_postal_code": "95947",
"origin_country": "USA",
"destination_city": "Dallas",
"destination_state": "TX",
"destination_postal_code": "75214",
"destination_country": "USA",
"ship_date": "11/10/2017",
"transport_type": 1,
"Vehicles": [
{
"vehicle_inop": 0,
"vehicle_make": "Datsun",
"vehicle_model": "240Z",
"vehicle_model_year": 1973,
"vehicle_type": "Car"
}
]
}
Lead with Three Vehicles and only the required fields (non-required fields can be submitted with blank information):
{
"AuthKey": "8c00130d-872f-4912-81c9-553f38ec61e0",
"first_name": "Jonah",
"last_name": "",
"phone": "(415) 621-1111",
"comment_from_shipper": "",
"destination_city": "",
"destination_country": "",
"destination_postal_code": "75214",
"destination_state": "",
"origin_city": "",
"origin_country": "",
"origin_postal_code": "95947",
"origin_state": "",
"ship_date": "11/10/2017",
"transport_type": 1,
"Vehicles": [
{
"vehicle_inop": 0,
"vehicle_make": "Datsun",
"vehicle_model": "240Z",
"vehicle_model_year": 1973,
"vehicle_type": ""
},
{
"vehicle_inop": 1,
"vehicle_make": "Ford",
"vehicle_model": "Focus",
"vehicle_model_year": 2000,
"vehicle_type": ""
},
{
"vehicle_inop": 0,
"vehicle_make": "Audi",
"vehicle_model": "A4",
"vehicle_model_year": 2017,
"vehicle_type": ""
}
]
}