--- title: "Respond to Dispatch" url: "https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665/operations/postRespondDispatch" --- > Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665.md # Respond to Dispatch `POST` `/api/fulfillments/id/{dispatchId}/respond` Operation ID: `postRespondDispatch` A carrier can accept or decline a load that has been assigned to them by the shipper. #### 👥 Customer Type - Carrier #### 📝 Important Notes - May only be used by the assigned carrier or a broker with the carrier profile that is assigned to. - Only dispatches with a status of `NOT_SIGNED` will be processed. ## Path parameters - `dispatchId` (string, uuid, required) - The ID of the dispatch to respond to. ## Header parameters - `If-Match` (integer, required) - This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the `ETag` header that was received on the preceding get call. - `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 - `202` - Accepted. Successful request. - `400` - Bad Request. Check the request payload. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. - `404` - Not Found. - `409` - Conflict. Update not allowed based on the current resource state. **Scenarios:** - Dispatch status is not `NOT_SIGNED`. - `requiresInspection` is true on the dispatch but `inspectionAcknowledged` is false in request. - `412` - Precondition Failed **Scenarios:** - RecordVersion (`If-Match` header) does not match. - Dispatch status is not NOT_SIGNED (invalid state for operation). - Resource modified by another request (stale ETag). - `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/id/{dispatchId}/respond: post: tags: - Dispatch summary: Respond to Dispatch description: >- A carrier can accept or decline a load that has been assigned to them by the shipper. #### 👥 Customer Type - Carrier #### 📝 Important Notes - May only be used by the assigned carrier or a broker with the carrier profile that is assigned to. - Only dispatches with a status of `NOT_SIGNED` will be processed. operationId: postRespondDispatch parameters: - name: dispatchId in: path description: The ID of the dispatch to respond to. required: true schema: type: string format: uuid example: d159acc0-e89b-12d3-a456-426614174000 - name: If-Match in: header description: This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the `ETag` header that was received on the preceding get call. required: true schema: type: integer example: 8675309 - 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: "`RespondToDispatchRequest`" content: application/json: schema: $ref: "#/components/schemas/RespondToDispatchRequest" examples: ex.: value: accept: true responses: "202": description: Accepted. Successful request. headers: Location: description: Contains the fully qualified URL of the newly created or updated resource. The final segment of the URL will equal the ID of the resource. schema: type: string example: "8675309" "400": description: Bad Request. Check the request payload. content: application/json: schema: $ref: "#/components/schemas/ErrorsAlt" "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/ErrorsAlt" "409": description: >- Conflict. Update not allowed based on the current resource state. **Scenarios:** - Dispatch status is not `NOT_SIGNED`. - `requiresInspection` is true on the dispatch but `inspectionAcknowledged` is false in request. content: application/json: schema: $ref: "#/components/schemas/ErrorsAlt" "412": description: |- Precondition Failed **Scenarios:** - RecordVersion (`If-Match` header) does not match. - Dispatch status is not NOT_SIGNED (invalid state for operation). - Resource modified by another request (stale ETag). content: application/json: schema: $ref: "#/components/schemas/ErrorsAlt" "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: RespondToDispatchRequest: type: object properties: accept: type: boolean description: Indicates whether the dispatch should be accepted or declined. example: true inspectionAcknowledged: type: boolean description: Indicates whether the require inspection requirement was acknoowledged. default: false example: true carrierEstimatedPickupDate: type: string description: The date the carrier estimates the vehicle will be picked up, in UTC/ISO 8601 format. Only the date portion of the value passed will be saved. format: date-time nullable: true example: 2025-07-15T00:00:00.000Z carrierEstimatedDeliveryDate: type: string description: The type of delivery date. Only the date portion of the value passed will be saved. format: date-time nullable: true example: 2025-08-15T00:00:00.000Z description: Details of the respond request. nullable: true 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. 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. 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 ```