--- title: "Create Carrier Match" url: "https://stage-api-docs.centraldispatch.com/apis/stage-membership-api-1-0-0/versions/50dc9109-f861-4ac9-a838-9ba774c3df98/operations/postCreateCarrierMatch" --- > Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-membership-api-1-0-0/versions/50dc9109-f861-4ac9-a838-9ba774c3df98.md # Create Carrier Match `POST` `/carrier-matches/ref/listings/id/{listingId}` Operation ID: `postCreateCarrierMatch` Requests ranked carrier recommendations for a listing and persists the match, returning up to 10 carriers enriched with ratings, tenure, contact information, preferred-network status, and advisory warnings. #### 👥 Customer Type - Shipper #### 📝 Important Notes - Requires an authorized Premium shipper account. - 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. - If no carriers are matched, the response is still `201` with an empty `carriers` collection — the match is persisted and has an ID. ## Path parameters - `listingId` (string, required) - The ID of the listing. ## Header parameters - `X-CoxAuto-Caller-Channel` (string, optional) - Marks the source of the carrier match request. The only supported value is `API`; the header may also be omitted. - `X-CoxAuto-AcceptFallback` (string, optional) - Opts into a degraded response when carrier rating data is temporarily unavailable. When `true`, `overallRating` and `recentRating` are omitted from the response and a `Warning` header is returned instead of a `503`. - `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`. ## Responses - `201` - Created. Successful request. - `400` - Bad Request. Check the request payload. **Scenarios:** - `listingId` is malformed. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. **Scenarios:** - Caller's account is not an authorized Premium shipper account. - `404` - Not Found. **Scenarios:** - Listing not found. - `406` - Not Acceptable **Scenarios:** - `Accept` version header is missing or invalid - v1 API requires: `Accept: application/vnd.coxauto.v1+json`. - `422` - Unprocessable Entity. Errors found in the request. **Scenarios:** - Listing is on a private marketplace. - Listing is inactive. - Listing is a non-US listing. - Caller does not have access to the listing's marketplace. - Listing price is out of range. - No drivable distance between stops. - Price-per-distance ratio is out of range. - Listing does not qualify for carrier matching for a reason not covered by the other scenarios. - `429` - Too Many Requests. Rate limit exceeded. - `500` - Error. - `503` - Service Unavailable. Temporary service interruption. **Scenarios:** - Carrier rating data is temporarily unavailable. ## 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: /carrier-matches/ref/listings/id/{listingId}: post: tags: - Carrier Matches summary: Create Carrier Match description: >- Requests ranked carrier recommendations for a listing and persists the match, returning up to 10 carriers enriched with ratings, tenure, contact information, preferred-network status, and advisory warnings. #### 👥 Customer Type - Shipper #### 📝 Important Notes - Requires an authorized Premium shipper account. - 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. - If no carriers are matched, the response is still `201` with an empty `carriers` collection — the match is persisted and has an ID. operationId: postCreateCarrierMatch parameters: - name: listingId in: path description: The ID of the listing. required: true schema: type: string example: "42220470" - name: X-CoxAuto-Caller-Channel in: header description: Marks the source of the carrier match request. The only supported value is `API`; the header may also be omitted. schema: type: string example: API - name: X-CoxAuto-AcceptFallback in: header description: Opts into a degraded response when carrier rating data is temporarily unavailable. When `true`, `overallRating` and `recentRating` are omitted from the response and a `Warning` header is returned instead of a `503`. schema: type: string example: "true" - 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 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: https://example.server/examples/id/12345 Warning: description: "Present when the response is degraded due to temporarily unavailable carrier rating data and `X-CoxAuto-AcceptFallback: true` was supplied. Value is `299`." schema: type: string content: application/json: schema: $ref: "#/components/schemas/CarrierMatchResourceResponse" "400": description: |- Bad Request. Check the request payload. **Scenarios:** - `listingId` is malformed. 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:** - Caller's account is not an authorized Premium shipper account. "404": description: |- Not Found. **Scenarios:** - Listing not found. content: application/json: schema: $ref: "#/components/schemas/Errors" "406": description: >- Not Acceptable **Scenarios:** - `Accept` version header is missing or invalid - v1 API requires: `Accept: application/vnd.coxauto.v1+json`. content: application/json: schema: $ref: "#/components/schemas/Errors" "422": description: >- Unprocessable Entity. Errors found in the request. **Scenarios:** - Listing is on a private marketplace. - Listing is inactive. - Listing is a non-US listing. - Caller does not have access to the listing's marketplace. - Listing price is out of range. - No drivable distance between stops. - Price-per-distance ratio is out of range. - Listing does not qualify for carrier matching for a reason not covered by the other scenarios. 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. **Scenarios:** - Carrier rating data is temporarily unavailable. security: - Bearer: [] security: - Bearer: [] components: schemas: CarrierMatchResourceResponse: type: object properties: href: type: string description: Canonical self URL for the created carrier match. nullable: true example: https://membership-api.centraldispatch.com/carrier-matches/id/c1a7e9d0-4b3f-4a1e-9c6d-8f2b5a7e0c14 carriers: type: array items: $ref: "#/components/schemas/CarrierMatchResponse" description: Collection of ranked, enriched carriers matched for the listing. Empty when no carriers matched. nullable: true description: The created carrier match, with carriers ranked and enriched. 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. CarrierMatchResponse: type: object properties: href: type: string description: Canonical self URL for the carrier's customer resource. nullable: true example: https://membership-api.centraldispatch.com/customers/id/0ca91a43-fbee-4c05-9a6c-aa5c63888f5c customerId: type: string description: The Central Dispatch customer ID of the customer. format: uuid example: 0ca91a43-fbee-4c05-9a6c-aa5c63888f5c customerName: type: string description: The carrier name. nullable: true example: Acu Logistics address: $ref: "#/components/schemas/AddressResponse" phone: type: string description: The carrier's business phone number. nullable: true example: 800-555-0142 establishedIn: type: string description: The year the company was established. nullable: true example: "1998" joinedOn: type: string description: The date the company joined the platform, in UTC/ISO 8601 format. format: date-time nullable: true example: 2024-09-10T00:00:00Z usDotAuthorizedState: type: string description: The state under which the carrier's USDOT number is authorized to operate, if on file; otherwise `null`. nullable: true example: OH overallRating: $ref: "#/components/schemas/CarrierRating" recentRating: $ref: "#/components/schemas/CarrierRating" isPreferred: type: boolean description: Whether this carrier is in the calling shipper's preferred-carrier network. example: true warnings: type: array items: $ref: "#/components/schemas/CarrierWarning" description: Collection of advisory warnings derived from FMCSA and audit data. nullable: true description: A carrier matched for a listing, enriched with rating, tenure, contact, and network information. 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. 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. CarrierRating: type: object properties: averageRatings: type: number description: Average rating across the period. format: double example: 4.7 totalRatings: type: integer description: Number of ratings the average is computed from. format: int32 example: 42 periodDays: type: integer description: Rating window in days; `null` means lifetime, `90` means the recent (90-day) window. format: int32 nullable: true example: 90 description: A carrier's rating summary for a given period. nullable: true CarrierWarning: type: object properties: code: type: string description: Namespaced warning code (`carrier.fmcsa.*` or `carrier.audit.*`). nullable: true example: carrier.fmcsa.authority_revoked message: type: string description: Human-readable warning description. nullable: true example: FMCSA operating authority has been revoked. description: An advisory warning about a matched carrier. securitySchemes: Bearer: type: http scheme: Bearer ```