---
title: "Search Dispatches"
url: "https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665/operations/postSearchDispatches"
---

> Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665.md

# Search Dispatches

`POST` `/api/fulfillments/search`

Operation ID: `postSearchDispatches`

Get a collection of dispatch IDs based on the specified search criteria. #### 📝 Important Notes - If calling as a broker the `X-Profile-Type` header must be included to distinguish between calling as a dealer or carrier. - Possible values: `carrier`, `dealer`.

## Header parameters

- `X-Profile-Type` (string, optional) - Required when calling as a broker, use to specify the caller's role. The value must be either `carrier` or `shipper`. Default is `shipper`
- `Content-Type` (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 Content-Type header should be set to `application/vnd.coxauto.v1+json`.

## Request body

Content types: `application/json`

## Responses

- `200` - OK. Successful request.
- `400` - Bad Request. Check the request payload. **Scenarios:** - Request body is invalid JSON format.
- `401` - Unauthorized. Authentication failed or missing.
- `403` - Forbidden. The attempted action is not permitted.
- `422` - Unprocessable Entity. Errors found in the request.
- `429` - Too Many Requests. Rate limit exceeded.
- `500` - Error.
- `503` - Service Unavailable. Temporary service interruption.

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Fulfillment API
  version: 1.0.0
servers:
  - url: https://fulfillment-api.centraldispatch.com
    description: Production server
paths:
  /api/fulfillments/search:
    post:
      tags:
        - Dispatch
      summary: Search Dispatches
      description: >
        
        Get a collection of dispatch IDs based on the specified search criteria.


        #### 📝 Important Notes

        - If calling as a broker the `X-Profile-Type` header must be included to
        distinguish between calling as a dealer or carrier.
         - Possible values: `carrier`, `dealer`.
      operationId: postSearchDispatches
      parameters:
        - name: X-Profile-Type
          in: header
          description: Required when calling as a broker, use to specify the caller's
            role. The value must be either `carrier` or `shipper`. Default is
            `shipper`
          schema:
            type: string
          example: carrier
        - name: Content-Type
          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 Content-Type
            header should be set to `application/vnd.coxauto.v1+json`.
          required: true
          schema:
            type: string
          example: application/vnd.coxauto.v1+json
      requestBody:
        description: "`DispatchSearchRequest`"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DispatchSearchRequest"
            examples:
              ex.:
                value:
                  searchFields:
                    dispatchStatus:
                      - PENDING_PICKUP
                      - DELIVERED
                    dispatchDate:
                      op: RANGE
                      startDateTime: 2024-08-01T00:00:00Z
                      endDateTime: 2024-09-10T00:00:00Z
                  sortFields:
                    - name: actualPickUpDateTime
                      direction: ASCENDING
                    - name: estimatedDropOffDateTime
                      direction: ASCENDING
                    - name: needAction
                      direction: DESCENDING
                  limit: 10
                  offset: 0
      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/SearchDispatchResult"
        "400":
          description: |-
            Bad Request. Check the request payload.

            **Scenarios:**

             - Request body is invalid JSON format.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "401":
          description: Unauthorized. Authentication failed or missing.
        "403":
          description: Forbidden. The attempted action is not permitted.
        "422":
          description: Unprocessable Entity. Errors found in the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "429":
          description: Too Many Requests. Rate limit exceeded.
        "500":
          description: Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "503":
          description: Service Unavailable. Temporary service interruption.
      security:
        - Bearer: []
security:
  - Bearer: []
components:
  schemas:
    DispatchSearchRequest:
      type: object
      properties:
        searchFields:
          $ref: "#/components/schemas/SearchRequest"
        offset:
          type: integer
          description: Determines which record in the collection will be the first one
            displayed. This value is 1-based, meaning the count starts at 1.
            Please put this and `limit` at the end of the request.
          format: int32
          example: 10
        limit:
          type: integer
          description: The maximum number of items to be returned in the response. Please
            put this and `offset` at the end of the request.
          format: int32
          default: 50
          nullable: true
          example: 1
        sortFields:
          type: array
          items:
            $ref: "#/components/schemas/SortRequest"
          description: The fields to sort by.
          nullable: true
      description: Details of the dispatch search.
      nullable: true
    SearchDispatchResult:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
          description: A collection of dispatch IDs.
          nullable: true
          example:
            - d159acc0-e89b-12d3-a456-426614174000
        count:
          type: integer
          description: The maximum number of items to be returned in the response.
          format: int32
          example: 1
        totalRecords:
          type: integer
          description: The total count of resources in the collection.
          format: int64
          example: 100
      description: Details of a dispatch search.
    ErrorsAlt:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAlt"
          description: A collection of errors.
          nullable: true
      description: An error occurred, and the request could not be completed.
    SearchRequest:
      type: object
      properties:
        paymentStatus:
          type: array
          items:
            type: string
          description: "A collection of: The status of the payment of the dispatch.
            Values: `UNPAID`, `INVOICED`, `PARTIALLY_PAID`, `FULLY_PAID`."
          nullable: true
        dispatchStatus:
          type: array
          items:
            type: string
          description: "A collection of: Dispatch statuses e.g. `NEW`, `PENDING_DELIVERY`,
            `DELIVERED`, `PAID`, `REJECTED`, `CANCELED`."
          nullable: true
        pickUpCity:
          type: array
          items:
            type: string
          description: "A collection of: The pick up city."
          nullable: true
        pickUpState:
          type: array
          items:
            type: string
          description: "A collection of: The pick up state."
          nullable: true
        pickUpZip:
          type: array
          items:
            type: string
          description: "A collection of: The pick up ZIP code. Must be a valid United
            States ZIP code or Canadian postal code."
          nullable: true
        deliveryCity:
          type: array
          items:
            type: string
          description: "A collection of: The delivery city."
          nullable: true
        deliveryState:
          type: array
          items:
            type: string
          description: "A collection of: The delivery state."
          nullable: true
        deliveryZip:
          type: array
          items:
            type: string
          description: "A collection of: The delivery ZIP code."
          nullable: true
        externalId:
          type: array
          items:
            type: string
          description: "A collection of: An identifier managed by the user. Shippers can
            use this field to map a record (e.g. order, shipment, dispatch) in
            their local TMS to a Central Dispatch record. This value is
            displayed as the load number on the Central Dispatch website."
          nullable: true
        dispatchID:
          type: string
          description: "A collection of: The ID of the dispatch."
          nullable: true
        vin:
          type: array
          items:
            type: string
          description: "A collection of: The vehicle identification number (VIN)."
          nullable: true
        driverId:
          type: array
          items:
            type: string
          description: "A collection of: The Central Dispatch user ID of the driver."
          nullable: true
        shipperCompanyName:
          type: array
          items:
            type: string
          description: "A collection of: The shipper's company name."
          nullable: true
        shipperOrderId:
          type: array
          items:
            type: string
          description: "A collection of: The ID of the shipper order."
          nullable: true
        marketPlaceIds:
          type: array
          items:
            type: string
          description: "A collection of: 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."
          nullable: true
        externalCompanyIds:
          type: array
          items:
            type: string
          description: "A collection of: The ID of the Central Dispatch customer who is
            shipping the vehicle."
          nullable: true
        externalCompanyNames:
          type: array
          items:
            type: string
          description: "A collection of: The external company name."
          nullable: true
        externalVehicleIds:
          type: array
          items:
            type: string
          description: "A collection of: A vehicle identifier managed by the user.
            Shippers can use this field to map a vehicle record in their local
            TMS to a Central Dispatch record."
          nullable: true
        loadId:
          type: array
          items:
            type: string
          description: "A collection of: The load number."
          nullable: true
        carrierName:
          type: array
          items:
            type: string
          description: "A collection of: The carrier name."
          nullable: true
        carrierId:
          type: array
          items:
            type: string
          description: "A collection of: The ID of the Central Dispatch customer chosen by
            the shipper to move cars in the dispatch."
          nullable: true
        actualPickUpDateTime:
          type: string
          description: The actual pick up date and time, in UTC/ISO 8601 format.
          format: date-time
          nullable: true
        actualDropOffDateTime:
          type: string
          description: The actual delivery date and time, in UTC/ISO 8601 format.
          format: date-time
          nullable: true
        estimatedPickUpDateTime:
          type: string
          description: The estimated pick up date and time, in UTC/ISO 8601 format.
          format: date-time
          nullable: true
        estimatedDropOffDateTime:
          type: string
          description: The estimated delivery date and time, in UTC/ISO 8601 format.
          format: date-time
          nullable: true
        dispatchDate:
          $ref: "#/components/schemas/DateSearchRequest"
        listingIds:
          $ref: "#/components/schemas/ListingIdSearchRequest"
        dispatchIds:
          $ref: "#/components/schemas/DispatchIdsSearchRequest"
        driverIds:
          $ref: "#/components/schemas/DriverSearchRequest"
        isCarrierArchived:
          type: boolean
          description: Indicates if the carrier is archived.
          nullable: true
        isShipperArchived:
          type: boolean
          description: Indicates if the shipper is archived.
          nullable: true
      description: Details of search fields.
    SortRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the field to sort by.
          nullable: true
          example: actualPickUpDateTime
        direction:
          type: string
          description: "The direction of the sort. Values: `ASCENDING`, `DESCENDING`."
          nullable: true
          example: ASCENDING
      description: Details of search sort.
    ErrorAlt:
      type: object
      properties:
        errorID:
          type: string
          description: The ID of the error.
          nullable: true
          example: 157a16f0-503d-4256-ba60-a4876e8eb9bb
        code:
          type: string
          description: The code used for the issue.
          nullable: true
          example: resource.issue_type
        description:
          type: string
          description: A detailed message.
          nullable: true
          example: The issue happened because something is wrong.
        properties:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAltProperty"
          description: Properties related to the issue.
          nullable: true
      description: Details of an error or issue.
    DateSearchRequest:
      type: object
      properties:
        op:
          type: string
          description: "The operation type for the date comparison. Values: `RANGE`, `EQ`,
            `NEQ`."
          example: RANGE
        startDateTime:
          type: string
          description: The start date and time, in UTC/ISO 8601 format.
          format: date-time
        endDateTime:
          type: string
          description: The end date and time, in UTC/ISO 8601 format. Required for `RANGE`
            and must be equal or greater than `startDateTime`.
          format: date-time
      description: Search dispatch date request.
      nullable: true
    ListingIdSearchRequest:
      type: object
      properties:
        op:
          type: string
          description: "The operation type for the listing IDs. Values: `EQ`, `NEQ`,
            `RANGE`."
          example: EQ
        values:
          type: array
          items:
            type: string
          description: A collection of listing ID values.
          example:
            - "42220470"
            - 157a16f0-503d-4256-ba60-a4876e8eb9bb
      description: Search listing IDs information.
      nullable: true
    DispatchIdsSearchRequest:
      type: object
      properties:
        op:
          type: string
          description: "The operator to use. Values: `EQ`, `NEQ`."
          example: EQ
        values:
          type: array
          items:
            type: string
          description: A collection of dispatch IDs.
          example:
            - d159acc0-e89b-12d3-a456-426614174000
            - 157a16f0-503d-4256-ba60-a4876e8eb9bb
      description: Search dispatch IDs information.
      nullable: true
    DriverSearchRequest:
      type: object
      properties:
        op:
          type: string
          description: "The operation type for the driver IDs. Values: `EQ`, `NEQ`."
          example: EQ
        values:
          type: array
          items:
            type: string
          description: A collection of driver ID values.
          example:
            - d71b5750-e89b-12d3-a456-426614174000
            - 3ca6e1c2-98fb-4b4e-bfd8-ffaec58fb347
      description: Driver IDs search.
      nullable: true
    ErrorAltProperty:
      type: object
      properties:
        property:
          type: string
          description: The name of the property.
          nullable: true
          example: person
        value:
          type: string
          description: The value of the property.
          nullable: true
          example: J0hn D03
      description: Details of an error's property.
  securitySchemes:
    Bearer:
      type: http
      scheme: Bearer
```