externalReference

externalReference is your own id for the record a request comes from, for example the eBA record number or an ERP order number. Quatlas keeps it beside the request, visible only to your company.

Rules

• Required on every create, at most 100 characters. Leading and trailing spaces are removed.
• Unique within your company. The same reference again never opens a second request: the answer is 409 with Integration.DuplicateExternalReference, and the body names the request that already has it.
• Per mode. Live and sandbox are separate: a test key’s references never collide with live ones. A sandbox request, and its reference, is deleted after 30 days.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Integration.DuplicateExternalReference",
  "status": 409,
  "detail": "This externalReference was already used: the existing request is returned.",
  "code": "Integration.DuplicateExternalReference",
  "requestId": "<request-id>",
  "requestStatus": "Draft",
  "webUrl": "https://app.quatlasglobal.com/shipments/<request-id>",
  "livemode": true
}

status is the HTTP status of the problem; requestStatus is the existing request’s own status. A repeat never publishes the request again, even when it asks to.

Finding a request by your reference

You do not have to store the Quatlas id:

curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests?externalReference=EBA-2026-000123" \
  -H "Authorization: Bearer $QUATLAS_KEY"

The answer is the same status body as GET /shipment-requests/{id}. Without the parameter the answer is 400 (Integration.ExternalReferenceRequired); with a reference your company has not used, 404.

The deals made from a request can be listed by your reference too:

curl "https://app.quatlasglobal.com/api/integrations/v1/deals?externalReference=EBA-2026-000123" \
  -H "Authorization: Bearer $QUATLAS_KEY"

Send exactly one of externalReference or shipmentRequestId there, or the answer is 400 (Integration.DealFilterRequired).

In webhooks

Webhook bodies carry externalReference when your company owns the request (the shipper side). The carrier side of a deal receives null: a reference belongs to the company that made it.

Purchase order and cost centre

purchaseOrderNumber and costCenter are optional, at most 100 characters each, kept with the request and visible only to your company. They come back on every status read. Unlike externalReference, they need not be unique.