The /v3/carriers/refresh/list endpoint lets you retrieve the complete details of your onboarded carriers, beginning from a specified onboarding date.
For TMS integrators, this endpoint is most useful when your customer first adds their BrokerCarrier API key to their account on your platform. If they have a large number of onboarded carriers in BrokerCarrier that have not been ported to your system, you can use this endpoint to batch-import their entire carrier list.
In addition, you can use this endpoint as a convenient way to refresh the broker’s carrier list every 24-48 hours by specifying the current date or the previous day’s date as the beginning point.
Notes on this endpoint:
- Requires secret key. This endpoint must be called from the server side to avoid compromising your secret API key. Please do not use your secret key in client-side JavaScript.
- Potential for large responses. This endpoint can potentially return very large responses. The complete profile of a single carrier is typically about 3KB, and there can potentially be thousands of carriers in a brokers’s network. For this reason, we recommend handling requests to this endpoint asynchronously.
HTTP request
Method
URL
GETRequired parameters
Name
Type
Value(s)
pkstringYour public API key
skstringYour secret API key
emailstringEmail address of the BrokerCarrier user who is making the API call
start_datestringA date string in the following format:
Return values
This endpoint returns an object with the following keys and values.
Key
Type
Value
carriersarray[]An array of objects, each with the following fields:
{
}
{
objectobjectobjectobjectobjectobjectobjectobjectobjectarrayarraystringarrayarray}
responseobject{}An object with the following fields:
{
}
{
stringintegerinteger}
Example response
{
"carriers": [
{
"accounting": {
"poc_name": "JANE SMITH",
"phone": "5558675309",
"email": "jane@democarrier.com",
"address_1": "123 BOULEVARD ST",
"address_2": "",
"locality": "PHOENIX",
"state": "AZ",
"zip": "85034",
"factoring_company": "DENIM"
},
"authority": {
"dot_num": "012376549",
"dot_num_date": "2020-10-12",
"dot_num_age": {
"seconds": 67106601,
"days": 776.6967708333333
},
"operation": "interstate",
"docket_num": "01237654",
"scac": null,
"cbsa": null,
"oic_state": "AZ",
"oic_state_reg_num": null
},
"business": {
"name": "DEMO CARRIER LLC",
"address_1": "123 BOULEVARD ST",
"address_2": "",
"locality": "PHOENIX",
"state": "AZ",
"zip": "85034",
"country": "US",
"phone": "5558675309"
},
"cargo": [
"General Freight"
],
"contract_signature": {
"name": "JANE SMITH",
"title": "PRESIDENT",
"date_time": "2022-11-22 23:23:07.520912"
},
"dispatcher": {
"phone": "5558675309",
"email": "jane@democarrier.com"
},
"eld": {
"brand": "Samsara",
"key": "kj2h3498a7sdkjh23498a7sdkjh35"
},
"equipment": {
"drivers": 2,
"tractors": 2,
"reefers": 1
},
"insurance": {
"company": "PROGRESSIVE COMMERCIAL",
"tractors": "8004444487",
"reefers": "progressivecommercial@email.progressive.com"
},
"lane_preferences": [
{
"origin": {
"address_form": "PHOENIX, AZ",
"city": "PHOENIX",
"state": "AZ"
},
"destination": {
"address_form": "LOS ANGELES, CA",
"city": "LOS ANGELES",
"state": "CA"
}
},
{
"origin": {
"address_form": "PHOENIX, AZ",
"city": "PHOENIX",
"state": "AZ"
},
"destination": {
"address_form": "EL PASO, TX",
"city": "EL PASO",
"state": "TX"
}
},
{
"origin": {
"address_form": "PHOENIX, AZ",
"city": "PHOENIX",
"state": "AZ"
},
"destination": {
"address_form": "DENVER, CO",
"city": "DENVER",
"state": "CO"
}
}
],
"lanes_covered": [
{
"origin": {
"address_form": "PHOENIX, AZ 85034",
"city": "PHOENIX",
"state": "AZ",
"zip": "85034"
},
"destination": {
"address_form": "EL PASO, TX 79917",
"city": "EL PASO",
"state": "TX",
"zip": "79917"
}
}
],
"network_status": "approved",
"operation_classification": [
"Authorized for Hire"
],
"services": [
"expedited",
"gps",
"ltl",
"refrigerated"
]
}
# This array can potentially contain thousands of objects like the above.
],
"response": {
"date_time": "2022-11-27 16:43:21 UTC",
"timestamp": 1669567401,
"status": 200
}
}