--- title: "Start Negotiation" url: "https://api-docs.centraldispatch.com/apis/offer-api-1-0-0/versions/a6eed1ce-f16b-440b-a2ed-bc3e4dcd83c8/operations/postNegotiation" --- > Full API specification: https://api-docs.centraldispatch.com/apis/offer-api-1-0-0/versions/a6eed1ce-f16b-440b-a2ed-bc3e4dcd83c8.md # Start Negotiation `POST` `/negotiations` Operation ID: `postNegotiation` Initiate an offer negotiation on a listing. #### 📝 Important Notes - The response will contain a `Location` header that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource. - The response will include an `ETag` header, which should be used for the `If-Match` header in subsequent updates. #### 🎯 Preferred Carrier Offers A Premium Public Shipper (an active Premium Dealer/Broker subscription in the Public Marketplace, `marketplaceId 10000`) can use this endpoint to send a Preferred Carrier Offer directly to a specific carrier in their preferred network by supplying `carrierId`. The stricter Preferred Carrier Offer rules below apply only when the listing is a V2 listing (`listingId >= 300000000`), the request's `marketplaceId` is a Public Marketplace, and the listing is non-searchable (not shown on the load board); direct offers on listings outside those conditions are processed as standard negotiations. For a qualifying listing: - Single Public Marketplace only — listings linked to multiple marketplaces are rejected. - SLA: duration, time zone, rollover time. - Stops (for both origin and destination): address, city, state, zip code, location type, contact name, contact phone. For the preferred offer being created: - `amount` must exactly equal the listing's `price.total` — no other value is accepted. - `expirationDateTime` must not exceed the listing's `expirationDate`, if one is set. - `carrierId` must be in the shipper's preferred carrier network. - At most 5 active (`AWAITING_CARRIER`) offers per listing. ## Header parameters - `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 - `201` - Created. Successful request. - `400` - Bad Request. Check the request payload. **Scenarios:** - Missing or empty `listingId`. - Missing or empty `customerId` (cannot be Guid.Empty). - Missing or empty `receiverCustomerId` (cannot be Guid.Empty). - `requestedPrice` must be greater than 0. - `requestedPrice` must be less than or equal to 99999999. - `amount` must be greater than 0. - `amount` must be less than or equal to 99999999. - Missing or empty `pickupDate`. - Missing or empty `deliveryDate`. - `deliveryDate` must not be before `pickupDate`. - `notes` must not exceed 250 characters. - Missing or empty `expirationDateUtc`. - `expirationDateUtc` must not be in the past (must be >= DateTime.UtcNow). - Listing not found (no offer listing exists for the specified `listingId`). - Listing status not ACTIVE (attempting to initiate negotiation on listing that's PENDING, EXPIRED, or CANCELLED). - `customerId` equals `receiverCustomerId` (they must be different parties). - Neither `customerId` nor `receiverCustomerId` equals the listing's `shipperId` (one party must be the shipper/listing owner). - For auto-accept negotiations: `amount` must exactly match the listing's `originalAsk` price. - Invalid `marketplaceId`. - Non-archived negotiation already exists for this carrier and listing. - `pickupDate` is null when SLA rules require it. - `deliveryDate` is null when SLA rules require it. - `pickupDate` falls outside allowed SLA date range. - `deliveryDate` falls outside allowed SLA date range. - Negotiation for this carrier has already been created - Preferred Carrier Offer: listing is missing required SLA, stop, vehicle, price, or date details. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. **Scenarios:** - Preferred Carrier Offer: `carrierId` is not in the shipper's preferred carrier network. - `422` - Unprocessable Entity. Errors found in the request. **Scenarios:** - Preferred Carrier Offer: listing is linked to more than one marketplace (a single Public Marketplace is required). - Preferred Carrier Offer: `amount` does not exactly match the listing's price. - Preferred Carrier Offer: `expirationDateTime` is later than the listing's expiration date. - Preferred Carrier Offer: maximum number of active offers already sent for this listing (5 per listing). - `429` - Too Many Requests. Rate limit exceeded. - `500` - Error. - `503` - Service Unavailable. Temporary service interruption. ## OpenAPI definition ```yaml openapi: 3.0.1 info: title: Offer API version: 1.0.0 servers: - url: https://prod-offers-api.awscal2.manheim.com description: Production server paths: /negotiations: post: tags: - Negotiations summary: Start Negotiation description: >- Initiate an offer negotiation on a listing. #### 📝 Important Notes - The response will contain a `Location` header that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource. - The response will include an `ETag` header, which should be used for the `If-Match` header in subsequent updates. #### 🎯 Preferred Carrier Offers A Premium Public Shipper (an active Premium Dealer/Broker subscription in the Public Marketplace, `marketplaceId 10000`) can use this endpoint to send a Preferred Carrier Offer directly to a specific carrier in their preferred network by supplying `carrierId`. The stricter Preferred Carrier Offer rules below apply only when the listing is a V2 listing (`listingId >= 300000000`), the request's `marketplaceId` is a Public Marketplace, and the listing is non-searchable (not shown on the load board); direct offers on listings outside those conditions are processed as standard negotiations. For a qualifying listing: - Single Public Marketplace only — listings linked to multiple marketplaces are rejected. - SLA: duration, time zone, rollover time. - Stops (for both origin and destination): address, city, state, zip code, location type, contact name, contact phone. For the preferred offer being created: - `amount` must exactly equal the listing's `price.total` — no other value is accepted. - `expirationDateTime` must not exceed the listing's `expirationDate`, if one is set. - `carrierId` must be in the shipper's preferred carrier network. - At most 5 active (`AWAITING_CARRIER`) offers per listing. operationId: postNegotiation parameters: - 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: "`InitiateNegotiationModel`" content: application/json: schema: $ref: "#/components/schemas/InitiateNegotiationModel" examples: ex.: value: amount: 300 carrierId: 0ca91a43-fbee-4c05-9a6c-aa5c63888f5c deliveryDate: 2025-10-04T00:00:00.000Z expirationDateTime: 2025-11-20T00:00:00.000Z listingId: "42220470" marketplaceId: 10000 pickupDate: 2025-09-27T00:00:00.000Z responses: "201": description: Created. 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. **Scenarios:** - Missing or empty `listingId`. - Missing or empty `customerId` (cannot be Guid.Empty). - Missing or empty `receiverCustomerId` (cannot be Guid.Empty). - `requestedPrice` must be greater than 0. - `requestedPrice` must be less than or equal to 99999999. - `amount` must be greater than 0. - `amount` must be less than or equal to 99999999. - Missing or empty `pickupDate`. - Missing or empty `deliveryDate`. - `deliveryDate` must not be before `pickupDate`. - `notes` must not exceed 250 characters. - Missing or empty `expirationDateUtc`. - `expirationDateUtc` must not be in the past (must be >= DateTime.UtcNow). - Listing not found (no offer listing exists for the specified `listingId`). - Listing status not ACTIVE (attempting to initiate negotiation on listing that's PENDING, EXPIRED, or CANCELLED). - `customerId` equals `receiverCustomerId` (they must be different parties). - Neither `customerId` nor `receiverCustomerId` equals the listing's `shipperId` (one party must be the shipper/listing owner). - For auto-accept negotiations: `amount` must exactly match the listing's `originalAsk` price. - Invalid `marketplaceId`. - Non-archived negotiation already exists for this carrier and listing. - `pickupDate` is null when SLA rules require it. - `deliveryDate` is null when SLA rules require it. - `pickupDate` falls outside allowed SLA date range. - `deliveryDate` falls outside allowed SLA date range. - Negotiation for this carrier has already been created - Preferred Carrier Offer: listing is missing required SLA, stop, vehicle, price, or date details. content: application/json: schema: $ref: "#/components/schemas/Errors" "401": description: Unauthorized. Authentication failed or missing. "403": description: >- Forbidden. The attempted action is not permitted. **Scenarios:** - Preferred Carrier Offer: `carrierId` is not in the shipper's preferred carrier network. "422": description: >- Unprocessable Entity. Errors found in the request. **Scenarios:** - Preferred Carrier Offer: listing is linked to more than one marketplace (a single Public Marketplace is required). - Preferred Carrier Offer: `amount` does not exactly match the listing's price. - Preferred Carrier Offer: `expirationDateTime` is later than the listing's expiration date. - Preferred Carrier Offer: maximum number of active offers already sent for this listing (5 per listing). 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: InitiateNegotiationModel: type: object properties: listingId: type: string description: The ID of the listing. example: "42220470" carrierId: type: string description: The ID of the Central Dispatch customer the shipper wants to move cars in the dispatch. If a shipper is making the offer this is required. For a Preferred Carrier Offer, this must be a carrier in the shipper's preferred carrier network. format: uuid nullable: true example: 0ca91a43-fbee-4c05-9a6c-aa5c63888f5c amount: minimum: 0 type: number description: The balance amount that will be due after the COD/COP payment is applied. format: double example: 300 pickupDate: type: string description: The date the pick up is scheduled, in UTC/ISO 8601 format. Will default to the listing pick up date if not specified. format: date-time nullable: true example: 2025-09-27T00:00:00.000Z deliveryDate: type: string description: The desired delivery date of the listing, in UTC/ISO 8601 format. Will default to the listing delivery date if not specified. format: date-time nullable: true example: 2025-10-04T00:00:00.000Z marketplaceId: type: integer 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." format: int32 example: 10000 expirationDateTime: type: string description: The expiration date of the listing, in UTC/ISO 8601 format. format: date-time example: 2025-11-20T00:00:00.000Z description: Details of a negotiation. 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. 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. securitySchemes: Bearer: type: http scheme: Bearer ```