---
title: "Search Customers"
url: "https://api-docs.centraldispatch.com/apis/membership-api-1-0-0/versions/565f78cb-7a6d-42ef-bd8b-1af2d1394eef/operations/getSearchCustomers"
---

> Full API specification: https://api-docs.centraldispatch.com/apis/membership-api-1-0-0/versions/565f78cb-7a6d-42ef-bd8b-1af2d1394eef.md

# Search Customers

`GET` `/customers`

Operation ID: `getSearchCustomers`

Get a collection of operational customers based on the specified search criteria.

## Query parameters

- `marketplace` (integer, int32, required) - The ID of the Central Dispatch Marketplace. There are three types of Marketplaces: - **Public**: The public Marketplace ID is `10000`. - **Test**: Test Marketplace IDs will be provided to you by Central Dispatch. - **Private**: Private Marketplace IDs will be provided to you by Central Dispatch, if necessary.
- `name` (string, optional) - The company name of the customer. If supplied, must be at least 3 characters in length.
- `mcNumber` (string, optional) - Motor carrier number (MC Number) or authority number.
- `phoneNumber` (string, optional) - The phone number of the customer.
- `email` (string, optional) - The email address of the contact. Must be a valid email address format.
- `usDotNumber` (string, optional) - The US Department of Transportation (USDOT) number.
- `limit(startingPoint,numberOfResults)` (string, optional) - The maximum number of items to be returned in the response. - `startingPoint` is 1-based integer, default 1. - `numberOfResults` is an integer, default 25, maximum 500.

## Header parameters

- `Accept` (string, required) - The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Accept header should be set to `application/vnd.coxauto.v1+json`.

## Responses

- `200` - OK. Successful request.
- `400` - Bad Request. Check the request payload. **Scenarios:** - Parsing error from invalid query string syntax. - `limit` value not between 1 and 500 (e.g., limit(1,501) or limit(1,0)). - `marketplaceId` is invalid or not provided. - No optional search parameters provided (must provide at least one: `name`, `email`, `phoneNumber`, `mcNumber`, or `usDotNumber`). - Name parameter provided but less than 3 characters.
- `401` - Unauthorized. Authentication failed or missing.
- `403` - Forbidden. The attempted action is not permitted.
- `404` - Not Found.
- `429` - Too Many Requests. Rate limit exceeded.
- `500` - Error.
- `503` - Service Unavailable. Temporary service interruption.

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Membership API
  version: 1.0.0
servers:
  - url: https://membership-api.centraldispatch.com
    description: Production server
paths:
  /customers:
    get:
      tags:
        - Customers
      summary: Search Customers
      description: Get a collection of operational customers based on the specified
        search criteria.
      operationId: getSearchCustomers
      parameters:
        - name: marketplace
          in: query
          description: "The ID of the Central Dispatch Marketplace. There are three types
            of Marketplaces:\r

            \r

            - **Public**: The public Marketplace ID is `10000`.\r

            - **Test**: Test Marketplace IDs will be provided to you by Central
            Dispatch.\r

            - **Private**: Private Marketplace IDs will be provided to you by
            Central Dispatch, if necessary."
          required: true
          schema:
            type: integer
            format: int32
          example: 10000
        - name: name
          in: query
          description: The company name of the customer. If supplied, must be at least 3
            characters in length.
          schema:
            minLength: 3
            type: string
            default: null
            nullable: true
          example: The Transport Co.
        - name: mcNumber
          in: query
          description: Motor carrier number (MC Number) or authority number.
          schema:
            type: string
            default: null
            nullable: true
          example: MC 123456
        - name: phoneNumber
          in: query
          description: The phone number of the customer.
          schema:
            type: string
            default: null
            nullable: true
          example: 800-555-9090
        - name: email
          in: query
          description: The email address of the contact. Must be a valid email address
            format.
          schema:
            type: string
            default: null
            nullable: true
          example: trans-port@notgmail.com
        - name: usDotNumber
          in: query
          description: The US Department of Transportation (USDOT) number.
          schema:
            type: string
            default: null
            nullable: true
          example: USDOT 1234567
        - name: limit(startingPoint,numberOfResults)
          in: query
          description: |-
            The maximum number of items to be returned in the response.
             - `startingPoint` is 1-based integer, default 1.
             - `numberOfResults` is an integer, default 25, maximum 500.
          schema:
            type: string
          example: limit(1,10)
        - name: Accept
          in: header
          description: The major version of the API to make a request against. This is a
            custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to
            request a resource from version 1.x.x of an API, the Accept header
            should be set to `application/vnd.coxauto.v1+json`.
          required: true
          schema:
            type: string
          example: application/vnd.coxauto.v1+json
      responses:
        "200":
          description: OK. Successful request.
          headers:
            X-CoxAuto-Media-Type:
              description: Contains the major version and format information.
              schema:
                type: string
              example: coxauto.v1; format=json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerSearchCollection"
        "400":
          description: >-
            Bad Request. Check the request payload.


            **Scenarios:**

             - Parsing error from invalid query string syntax.
             - `limit` value not between 1 and 500 (e.g., limit(1,501) or limit(1,0)).
             - `marketplaceId` is invalid or not provided.
             - No optional search parameters provided (must provide at least one: `name`, `email`, `phoneNumber`, `mcNumber`, or `usDotNumber`).
             - Name parameter provided but less than 3 characters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "401":
          description: Unauthorized. Authentication failed or missing.
        "403":
          description: Forbidden. The attempted action is not permitted.
        "404":
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "429":
          description: Too Many Requests. Rate limit exceeded.
        "500":
          description: Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "503":
          description: Service Unavailable. Temporary service interruption.
      security:
        - Bearer: []
security:
  - Bearer: []
components:
  schemas:
    CustomerSearchCollection:
      required:
        - href
        - count
        - items
        - limit
      type: object
      properties:
        href:
          type: string
          description: The URL used to query the current collection of the resource.
          example: https://membership-api.centraldispatch.com/customers/?start=5&limit=1&name=acu
        count:
          type: integer
          description: The total count of resources in the collection.
          format: int32
          example: 23
        items:
          type: array
          items:
            $ref: "#/components/schemas/CustomerSearchResponse"
          description: A collection of records.
        limit:
          type: integer
          description: The maximum number of items to be returned in the response.
          format: int32
          example: 1
      description: A collection of customers.
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
          description: A collection of errors.
          nullable: true
      description: An error occurred, and the request could not be completed.
    CustomerSearchResponse:
      type: object
      properties:
        customerName:
          type: string
          description: The customer's name.
          nullable: true
          example: Acu Logistics
        customerId:
          type: string
          description: The Central Dispatch customer ID of the customer.
          nullable: true
          example: d5c62b14-cbd1-11ee-9a0e-0242ac110002
        email:
          type: string
          description: The email address of the customer.
          nullable: true
          example: trans-port@notgmail.com
        phoneNumbers:
          type: array
          items:
            $ref: "#/components/schemas/PhoneResponse"
          description: A collection of phone numbers associated with the customer.
          nullable: true
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/AddressResponse"
          description: A collection of addresses associated with the customer.
          nullable: true
        customerAuthorityNumbers:
          type: array
          items:
            $ref: "#/components/schemas/AuthorityNumberResponse"
          description: A collection of authority numbers associated with the customer.
          nullable: true
      description: A customer record.
    Error:
      type: object
      properties:
        code:
          type: string
          description: The code used for the issue.
          nullable: true
          example: resource.issue_type
        message:
          type: string
          description: A detailed message.
          nullable: true
          example: The issue happened because something is wrong.
        property:
          type: string
          description: The property to which the issue is associated.
          nullable: true
          example: person
        properties:
          type: object
          additionalProperties:
            type: string
          description: Additional properties related to the issue.
          nullable: true
          example:
            firstName: D0nn@
            lastName: Sm!th
      description: Details of an error or issue.
    PhoneResponse:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phone number of the contact.
          nullable: true
          example: 949-555-1323
        type:
          type: string
          description: The type of phone number (e.g., BILLING, LISTING, LOCAL).
          nullable: true
          example: LOCAL
        extension:
          type: string
          description: The phone number extension.
          nullable: true
          example: "303"
        notes:
          type: string
          description: Additional notes about the phone number.
          nullable: true
          example: Primary contact number
      description: Details of a customer's phone number.
    AddressResponse:
      type: object
      properties:
        streetAddress:
          type: string
          description: The street address.
          nullable: true
          example: 345 W Elm St.
        streetAddress2:
          type: string
          description: Additional street address line.
          nullable: true
          example: 2nd Floor
        city:
          type: string
          description: The city.
          nullable: true
          example: Anaheim
        state:
          type: string
          description: The state.
          nullable: true
          example: CA
        zipcode:
          type: string
          description: The ZIP code. Must be a valid United States ZIP code or Canadian
            postal code.
          nullable: true
          example: "92802"
        type:
          type: string
          description: The type of address (e.g., PRIMARY, LOCAL, BILLING).
          nullable: true
          example: PRIMARY
      description: Details of a customer's address.
    AuthorityNumberResponse:
      type: object
      properties:
        number:
          type: string
          description: The authority number assigned to the customer.
          nullable: true
          example: DL 01-00673-10
        verified:
          type: boolean
          description: Indicates whether the authority number is verified.
          nullable: true
          example: true
        type:
          type: string
          description: The type of authority number.
          nullable: true
          example: DEALER_LICENSE
      description: Details of a customer's authority number.
  securitySchemes:
    Bearer:
      type: http
      scheme: Bearer
```