Skip to content
QuatlasQuatlas Developers

Reference numbers

Every shipment request, quote, deal and operation has a reference number beside its id. The id stays the API’s key; the number is the one people read out on the phone, find in an e-mail subject and type into your ERP or BPM screens. Store it next to the id.

Record Prefix Example Field
Shipment request REQ REQ-048213 requestNumber
Quote (a carrier’s offer) QTE QTE-731905 quoteNumber
Deal DEAL DEAL-206447 dealNumber
Operation (the deal’s shipment run) SHPT SHPT-012618 shipmentNumber

Format

Section titled “Format”
  • An upper-case prefix, a hyphen and digits: DEAL-206447.
  • At least six digits, zero-padded. Keep the number as text: SHPT-012618 and SHPT-12618 are different numbers.
  • Allow up to 16 characters. The range grows by a digit as it fills, so a seven-digit number can follow a six-digit one.
  • A number never changes, and is never reused. Records created before numbers existed have one too.
  • Numbers are unique per kind. The prefix tells the kinds apart: REQ-048213 and DEAL-048213 can both exist.
  • Numbers are not in sequence. Do not sort by them or read anything into the digits: the order of creation is in createdAt.

Where they appear

Section titled “Where they appear”
  • Reads. Every status, deal, operation, documents and costs body carries the numbers of the records it names, each null until that record exists: a request’s status gains dealNumber, quoteNumber and shipmentNumber once it is awarded and goes live.
  • Webhooks. Every delivery carries requestNumber, quoteNumber, dealNumber and shipmentNumber beside the ids. See Events.
  • The app and e-mails. People see the same numbers on every screen, with a copy button, and notification e-mails end their subject with the record’s number, for example [DEAL-206447].
  • Documents. The operation statement and the commission invoice print the numbers.

Reading a record by its number

Section titled “Reading a record by its number”
Terminal window
curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests/by-number/REQ-048213" \
  -H "Authorization: Bearer $QUATLAS_KEY"


curl "https://app.quatlasglobal.com/api/integrations/v1/deals/by-number/DEAL-206447" \
  -H "Authorization: Bearer $QUATLAS_KEY"


curl "https://app.quatlasglobal.com/api/integrations/v1/operations/by-number/SHPT-012618" \
  -H "Authorization: Bearer $QUATLAS_KEY"
  • Each answers exactly what the read by id answers, under the same scope (requests:read, deals:read, tracking:read) and the same rules: the request read with its ETag, the deal as your side sees it, the operation as GET /deals/{id}/tracking.
  • Any case, and the prefix is optional: deal-206447 and 206447 find the same deal. Another kind’s prefix (REQ-048213 on /deals/by-number) answers 400 Integration.InvalidBusinessNumber.
  • A number your company may not read answers 404, exactly like a number that does not exist: a request your company does not own, a deal or an operation it is not a party to.

Sandbox

Section titled “Sandbox”

Test records get numbers of the same shape. They come from a part of each range that live numbers never use, so a test number is never a live record’s number. A test key reads them by number in the sandbox, and a live key never finds them.