/api/p/v{version}/carriers/search

The Search Carriers API endpoint helps users retrieve carrier or subsidiary details efficiently by filtering through available data using IDs, MC numbers, DOT numbers, and Status. This functionality provides quick access to essential carrier information without needing to query the full dataset.

Request Parameters

The following parameter is required in the URL path:

Parameter	Type	Required	Description
version	String	Yes	The version of the API being requested.

Request Body

The request body must include the following parameters:

Parameter	Type	Required	Description
page	Number	Yes	The page number for pagination (starts from 0).
pageSize	Number	Yes	The number of results per page. PageSize must be greater than 0.
status	Array of Strings	Conditionally	Filter by carrier or subsidiary status (e.g., Pending, Active, Packet Completed). This field is required if the other conditionally required fields are left empty.
ids	Array of Strings (UUID)	Conditionally	Filter by specific carrier or subsidiary IDs. This field is required if the other conditionally required fields are left empty.
mcNumbers	Array of Strings	Conditionally	Filter by MC (Motor Carrier) numbers. This field is required if the other conditionally required fields are left empty.
dotNumbers	Array of Strings	Conditionally	Filter by USDOT numbers. This field is required if the other conditionally required fields are left empty.

At least one filter field (status, ids, mcNumbers, dotNumbers) must be provided along with pagination fields.

Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

curl --location 'https://integrations.alvys.com/api/p/v1/carriers/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data-raw '{
  "page": 0,
  "pageSize": 100,
  "status": ["Active", "Pending"],
  "ids": ["2e17c4d3-202d-4f27-b2fa-711c57435c5b"],
  "mcNumbers": ["1269221"],
  "dotNumbers": ["4204692"]
}'

Response Parameters

The response contains a list of carriers or subsidiaries matching the search criteria, each represented by the following parameters:

Parameter	Type	Description
page	Number	The current page number.
pageSize	Number	The number of items per page.
total	Number	The total number of matching items.
id	String (UUID)	The unique identifier of the carrier or subsidiary.
name	String	The name of the carrier or subsidiary.
address	Object	The address details (Street, City, State, ZipCode).
address.street	String	The street of the carrier’s address.
address.city	String	The city of the carrier’s address.
address.state	String	The state of the carrier’s address.
address.zipCode	String	The zip code of the carrier’s address.
mcNum	String	The MC (Motor Carrier) number.
usDotNum	String	The USDOT number.
type	String	Type of the entity (e.g., Carrier, Subsidiary).
status	String	Current status of the carrier or subsidiary (e.g., Active, Pending).
createdAt	String (Date-Time)	The creation date of the carrier/subsidiary record.
insuranceInfo	Array of Objects	A list of insurance policies associated with the carrier.
insuranceInfo.type	String	The type of insurance (e.g., Auto, Cargo, General, Workers Compensation).
insuranceInfo.policyNumber	String	The insurance policy number.
insuranceInfo.expirationDate	String (Date-Time)	The expiration date of the insurance policy.
insuranceInfo.amount	Number	The coverage amount of the insurance policy.
insuranceInfo.agent	Object	Information about the insurance agent.
insuranceInfo.agent.company	String	The name of the agent’s company.
insuranceInfo.agent.name	String	The name of the insurance agent.
insuranceInfo.notes	String	Notes associated with the insurance policy.

Example Response

{
  "page": 0,
  "pageSize": 100,
  "total": 1,
  "items": [
    {
      "id": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0",
      "name": "EVENT PRO LOGISTICS",
      "address": {
        "street": "3749 E 150 S",
        "city": "TIPTON",
        "state": "IN",
        "zipCode": "46072"
      },
      "mcNum": "63504",
      "usDotNum": "4204692",
      "type": "Subsidiary",
      "status": "Active",
      "createdAt": "2024-04-02T08:42:31.269118+00:00"
       "insuranceInfo": [
        {
          "type": "Auto",
          "policyNumber": "2445",
          "expirationDate": "2030-11-14T00:00:00+00:00",
          "amount": 0.0,
          "agent": {
            "company": "PG Company",
            "name": ""
          },
          "notes": ""
        }
      ]
    }
  ]
}

Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our Public API Postman Collection directly. Make sure to authorize yourself before trying a request.