OMC Couriers — Consignment API

Latest change: reference v1.18 (6 November 2026): tracking_url now has the form https://omccouriers.com/track/?label=<label>. Links in the old form still work. Store and pass on tracking_url as given rather than building it yourself. Every change since v1.2 is listed, newest first, in Change history at the end of this page.

Overview

The Consignment API lets your system push consignments into our label allocation engine and get label numbers back, synchronously, in the same call. It is the inverse of a sales channel connection: instead of our system reaching out to yours on a schedule, your system reaches in, whenever you have an order ready to ship, using an API key you generate in Compass.

Everything after the HTTP boundary — validation, label selection, serial allocation — is the same pipeline that handles a CSV import or a Shopify order, so a consignment created through this API behaves identically to one created any other way once it exists: it appears in Compass, it can be tracked, and (subject to the note on cancellation below) it can be cancelled.

Base URLs

Two deployments, each with its own base URL and its own keys — a key issued for one is rejected by the other with wrong_environment rather than a confusing invalid_key (see Authentication).

Authentication

Every request carries your API key as a bearer token:

Authorization: Bearer omc_live_7f3aK2p9xQ1z...

A key looks like omc_ + live or test + _ + 43 further characters. The live/test segment must match the environment you are calling — a live key against the sandbox, or a test key against production, is rejected immediately with an explicit error rather than a confusing "invalid key", so a finished test harness accidentally left pointed at the wrong place fails loudly on its first request.

Getting a key. You generate keys yourself in Compass, under Integrations → API access: Set up API access creates an API profile (the warehouse your parcels ship from and the default parcel size) and its first key together. A key is shown exactly once, when it is generated; copy it into wherever your system keeps its secrets before you leave that panel. After that Compass shows only its prefix, and neither you nor we can see the rest again. A lost key can't be recovered: revoke it and generate another. Keys are managed in Compass only; there is no key management endpoint in this API.

An API profile can hold two active keys at once, so you can rotate without downtime: generate the new key, deploy it, then revoke the old one. A revoked key is refused on the very next request, and is never switched back on. Sandbox Compass generates omc_test_ keys and live Compass omc_live_ keys; there is no choice to make. If a key can't be generated yet because your account's label set-up isn't finished, Compass says so; contact customer service to finish it.

Call GET /ping first. It is the fastest way to confirm your key works, see which environment you are talking to, and see which import profiles your key can use.

Rate limits and the batch cap

The two counters meter different things and are worth telling apart. The per-minute limit exists to stop a runaway client and is checked on every call — a reconciliation loop hammering GET /consignments trips it exactly like a create call would, and GET /consignments/{ref}/label in particular is not a cheap read: its first call makes a live request to the carrier. The per-hour limit meters actual work created and is only ever bumped by POST /consignments.

Exceeding either returns 429 with a Retry-After header, in seconds. Under a genuinely simultaneous burst you may occasionally be refused slightly before the nominal limit is reached — that is a deliberate trade (the counter is checked with no locking, so it can only ever under-admit, never over-admit) and not a bug to work around.

The batch cap of 50 is what makes a synchronous response practical at all: each item in a batch runs the full pipeline, including a live carrier call for some destinations. If you have more than 50 consignments ready at once, send them as multiple calls rather than waiting for a larger cap.

Endpoints

GET /ping

Auth and connectivity check. Call this first. Returns your customer name, which environment you are talking to (live or sandbox — the deployment, not your key's own live/test tag; see the note below), and the import profiles the key may use.

curl https://api.omccouriers.com/api/customer/v1/ping \
  -H "Authorization: Bearer omc_live_..."

200 OK
{
  "customer": "Acme Logistics Ltd",
  "environment": "live",
  "profiles": [
    { "profile_id": "3f2a1c9e-1111-4a2b-9c3d-abcdef123456", "name": "Default API profile" }
  ]
}

POST /consignments

Create 1–50 consignments in one call. See Worked examples for full request/response bodies. The short version:

• Response is 200 whenever the request itself was well-formed — even when every item failed to import, because a DRAFT item is a successful import at the HTTP level (the consignment exists, waiting to be completed) and a machine-readable failure would tell your retry logic to resend, which would then be treated as a duplicate. Check each item's own status and the top-level summary, not just the HTTP status code.
• Supply identifier per item to make retries safe: re-sending the same identifier for the same customer replays the original result rather than creating a second consignment, even if the original request is still being processed when the retry arrives. Omitting it means no protection — a genuine network retry with no identifier will create a duplicate consignment.
• An identifier stays tied to its first answer. A resend under an identifier you have used before replays the stored result and does not read the new payload at all, so a corrected resend under the same identifier changes nothing. To correct a REJECTED item, send it under a new identifier. To correct a DRAFT, finish it in Compass, or delete the draft there and resend. There are two exceptions, where a resend under the same identifier is processed afresh, as if new (new consignment_ref, no duplicate flag): the earlier attempt failed (unexpected_failure, nothing was created), or its draft was removed (the DRAFT consignment it created has since been deleted in Compass).
• Unrecognised or unsupported fields are never rejected — they are accepted and reported back in that item's warnings array, so a customer migrating a Scurri payload builder can send it here unmodified on day one and clean it up at leisure.
• The top-level environment field is the same one GET /ping returns — the deployment, not your key's own tag (see the note under Authentication).

GET /consignments

List consignments this API created for you, for reconciliation. Filters: created_from, created_to (both YYYY-MM-DD), status, order_number, identifier. Cursor-paginated, 100 per page, newest first — pass the response's next_cursor back as ?cursor= to fetch the next page; treat it as an opaque token, never construct one yourself.

GET /consignments?status=DRAFT&created_from=2026-08-01

200 OK
{
  "results": [
    { "consignment_ref": "CN0004417", "identifier": "wms-2026-98213",
      "order_number": "8384832", "status": "OPEN", "created_at": "2026-08-28T09:14:02.331Z" }
  ],
  "next_cursor": null
}

GET /consignments/{ref}

One consignment's current status: every parcel, its label number and tracking URL, whether it has been individually cancelled (is_voided), and the most recent tracking scan for it, if any. Only ever resolves a consignment this API created for you — a ref from another customer, or from another route into Enigma (the Compass portal, a CSV import), is reported as a plain 404.

200 OK
{
  "consignment_ref": "CN0004417", "identifier": "wms-2026-98213", "order_number": "8384832",
  "status": "OPEN", "created_at": "2026-08-28T09:14:02.331Z",
  "parcels": [
    { "parcel_index": 1, "is_voided": false, "label_number": "BY0001561392",
      "tracking_url": "https://omccouriers.com/track/?label=BY0001561392",
      "last_scan": { "event_type": "DELIVERY", "description": "Delivered",
                      "event_time": "2026-08-29T14:02:11.000Z",
                      "ext_carrier": null, "ext_tracking_number": "" } },
    { "parcel_index": 2, "is_voided": true, "label_number": "BY0001561393",
      "tracking_url": "https://omccouriers.com/track/?label=BY0001561393", "last_scan": null }
  ]
}

tracking_url is the parcel's public tracking page, showing its full tracking history: the link to pass on to your own customer. last_scan is only the latest event your customer can see; some scans are internal and never appear in either.

GET /consignments/{ref}/label

Returns the label PDF. ?format=thermal (default, one label per page) or ?format=a4 (two-up).

POST /consignments/{ref}/cancel

Cancels a consignment that has not yet shipped: voids every currently-live label on it and hands each label back, so it no longer counts as used. Not DELETE — the record, its now-voided labels and the reversal all stay for your own audit trail and ours. No request body. Only works on a consignment currently OPEN; cancelling one that is still DRAFT, already CANCELLED, or has shipped, returns 409.

200 means every parcel was cancelled and the consignment is now CANCELLED:

200 OK
{
  "consignment_ref": "CN0004417", "identifier": "wms-2026-98213", "order_number": "8384832",
  "status": "CANCELLED", "created_at": "2026-08-28T09:14:02.331Z",
  "parcels": [
    { "parcel_index": 1, "is_voided": true, "label_number": "BY0001561392",
      "tracking_url": "https://omccouriers.com/track/?label=BY0001561392", "last_scan": null }
  ]
}

207 Multi-Status
{
  "consignment_ref": "CN0004418", "identifier": "wms-2026-98214", "order_number": "8384833",
  "status": "OPEN", "created_at": "2026-08-28T09:20:11.042Z",
  "parcels": [
    { "parcel_index": 1, "is_voided": true,  "label_number": "BY0001561393", "tracking_url": "...", "last_scan": null },
    { "parcel_index": 2, "is_voided": false, "label_number": "BY0001561394", "tracking_url": "...", "last_scan": null }
  ],
  "detail": "1 of 2 parcels were cancelled. The other parcel couldn't be cancelled with the carrier just now and is still open — see each parcel's reason.",
  "results": [
    { "parcel_index": 1, "label_number": "BY0001561393", "status": "CANCELLED" },
    { "parcel_index": 2, "label_number": "BY0001561394", "status": "NOT_CANCELLED",
      "code": "carrier_error",
      "reason": "We couldn't cancel this parcel with the carrier just now, so it is still open. Try cancelling it again shortly, and contact customer service if it keeps failing." }
  ]
}

If the carrier refuses every parcel, nothing is cancelled and the response is 422 with "error": "carrier_error" and the same body — status still OPEN, every results entry NOT_CANCELLED. The carrier's own error text is never returned; customer service can see it.

Request field reference

Field names and envelope shape follow Scurri's Create Consignment API wherever a direct Enigma equivalent exists, so an existing Scurri integration is mostly a base-URL and credential change. A field Scurri sends that has no Enigma equivalent is always accepted, never rejected — it is silently recorded as ignored in that item's warnings array, so "ignored" never quietly means "lost" or "your integration is broken".

Consignment level

Customer service can also set up other fields to be read for label selection, including keys inside an object such as options.package_type or a top-level field such as custom_field_1. While such a field is set up, it and the object it sits in (here options) are no longer warned about as "not used by this API" or "not recognised" (since 1.12).

Packages

No packages array at all, or an empty one, produces a single parcel using every profile default.

Recipient

Address

Text values

These fields take text: identifier, order_number, shipping_method, warehouse_id, delivery_instructions; on recipient, name, first_name, last_name, company_name, email_address and contact_number; and on recipient.address, address1, address2, address3, city, state, postcode and country. In any of them (since 1.11):

• a number is taken as its text: 8384832 is "8384832", 12.5 is "12.5". Send a phone number as text if it starts with 0 or +: as a number it has already lost them;
• an object, a list, or true/false rejects that item (REJECTED, invalid_payload), with a reason naming the field in this reference's terms, such as "recipient.address.city must be text, not a list." Nothing is created for it; the other items in the request are unaffected;
• null is the same as leaving the field out.

Values that choose the label

Since 1.12. Your account's label selection rules, set up by customer service, decide which label each consignment gets. If your system already says which service it wants, per consignment, you can use that instead of relying on the rules' order:

1. In Compass, under Integrations → API access, add each value your system sends, exactly as it sends it, under the field it is sent in: service_id, shipping_method, or another field customer service has set up (such as options.package_type). Values are matched ignoring capital letters and extra spaces; punctuation counts, so Express|Parcel and Express | Parcel are different values.
2. Customer service links each value to a label. Compass shows which label each value leads to, or "Not linked yet". A linked value can't be edited or removed in Compass; contact customer service if it needs to change.

Then, for each consignment:

• A value that is linked to a label: the consignment gets that label. If that label can't be used — it doesn't deliver to the address, a parcel is over its limits, or there aren't enough left — the consignment is a DRAFT with that reason (for example no_label_for_destination or insufficient_balance naming that label). It is never quietly sent on a different label.
• No value, or a value that isn't linked: your other label rules choose, exactly as before. If you have values set up for that field, the result carries a warning such as "No label rule uses service_id 'Express|Satchel', so your default label rules were used.": usually a typo, or a value not yet added. If you have no values for that field, it is used silently, so an integration that always sends the same value keeps working without any set-up.
• If every one of your label rules is linked to a value and the consignment matches none, it is a DRAFT with no_matching_label_rule.

Customer service can also tie a label rule to one of your warehouses, so consignments shipping from it use a particular label. That follows the warehouse each consignment ships from, however warehouse_id named it, and needs nothing in the request.

Since 1.13, customer service can also limit a label rule to a weight or size: parcels weighing more than one figure and up to and including another, and/or whose longest side (the largest of length, width and height, whichever way round) is up to a given length. Weight is the parcel's chargeable weight when the label judges parcels by size as well as weight, otherwise the weight sent. Every parcel in the consignment must fit, and a parcel without all three dimensions (sent, or as defaults on your API profile) never fits a size limit. A consignment outside a rule's limits moves on to the next rule, but never from a linked value's rules to your other rules. If every rule that could apply has a limit and a parcel fits none of them, it is a DRAFT with no_label_rule_for_parcel_size.

Worked examples

A single consignment

POST /api/customer/v1/consignments
Authorization: Bearer omc_live_...
Content-Type: application/json

{
  "consignments": [
    {
      "identifier": "wms-2026-98213",
      "order_number": "8384832",
      "recipient": {
        "name": "John Doe",
        "contact_number": "07700 900123",
        "address": {
          "address1": "12 Ormeau Road", "city": "Belfast",
          "postcode": "BT7 1JR", "country": "GB"
        }
      },
      "packages": [ { "weight": 1.4, "length": 30, "width": 20, "height": 10 } ]
    }
  ]
}

200 OK
{
  "environment": "live",
  "summary": { "submitted": 1, "open": 1, "draft": 0, "rejected": 0, "duplicate": 0, "labels": { "BY": 1 } },
  "results": [
    {
      "index": 0, "identifier": "wms-2026-98213", "order_number": "8384832",
      "status": "OPEN", "consignment_ref": "CN0004417",
      "parcels": [
        { "parcel_index": 1, "label_number": "BY0001561392",
          "tracking_url": "https://omccouriers.com/track/?label=BY0001561392" }
      ],
      "warnings": []
    }
  ]
}

A multi-parcel consignment

One item, several packages — each becomes its own labelled parcel on the same consignment. Unlike a CSV upload, the API never merges separate items sharing an order number into one consignment: if you mean one consignment with several parcels, send one item with several entries in packages, exactly as below.

{
  "consignments": [
    {
      "identifier": "wms-2026-98214",
      "order_number": "8384840",
      "recipient": {
        "name": "Priya Shah", "contact_number": "07700 900456",
        "address": { "address1": "4 Falls Road", "city": "Belfast", "postcode": "BT12 6AA", "country": "GB" }
      },
      "packages": [
        { "weight": 3.2, "length": 40, "width": 30, "height": 25 },
        { "weight": 1.1 },
        { "weight": 0.6, "length": 15, "width": 15, "height": 10 }
      ]
    }
  ]
}

200 OK
{
  "environment": "live",
  "summary": { "submitted": 1, "open": 1, "draft": 0, "rejected": 0, "duplicate": 0, "labels": { "BY": 1 } },
  "results": [
    {
      "index": 0, "identifier": "wms-2026-98214", "order_number": "8384840",
      "status": "OPEN", "consignment_ref": "CN0004420",
      "parcels": [
        { "parcel_index": 1, "label_number": "BY0001561400", "tracking_url": "https://omccouriers.com/track/?label=BY0001561400" },
        { "parcel_index": 2, "label_number": "BY0001561401", "tracking_url": "https://omccouriers.com/track/?label=BY0001561401" },
        { "parcel_index": 3, "label_number": "BY0001561402", "tracking_url": "https://omccouriers.com/track/?label=BY0001561402" }
      ],
      "warnings": []
    }
  ]
}

A batch, with a mixed outcome

A batch of several consignments in one call. One item here is missing a phone number, so it lands in DRAFT rather than failing the whole call — the caller still gets 200 and must inspect each item's own status.

{
  "consignments": [
    {
      "identifier": "wms-2026-99001", "order_number": "9001",
      "recipient": { "name": "Sam Reid", "contact_number": "07700 900001",
        "address": { "address1": "1 High St", "city": "Lisburn", "postcode": "BT28 1AB", "country": "GB" } },
      "packages": [ { "weight": 1.0 } ]
    },
    {
      "identifier": "wms-2026-99002", "order_number": "9002",
      "recipient": { "name": "Alex Kim",
        "address": { "address1": "2 High St", "city": "Lisburn", "postcode": "BT28 1AC", "country": "GB" } },
      "packages": [ { "weight": 1.0 } ]
    }
  ]
}

200 OK
{
  "environment": "live",
  "summary": { "submitted": 2, "open": 1, "draft": 1, "rejected": 0, "duplicate": 0, "labels": { "BY": 1 } },
  "results": [
    { "index": 0, "identifier": "wms-2026-99001", "order_number": "9001", "status": "OPEN",
      "consignment_ref": "CN0004421",
      "parcels": [ { "parcel_index": 1, "label_number": "BY0001561410",
                     "tracking_url": "https://omccouriers.com/track/?label=BY0001561410" } ],
      "warnings": [] },
    { "index": 1, "identifier": "wms-2026-99002", "order_number": "9002", "status": "DRAFT",
      "consignment_ref": "CN0004422",
      "reason": "This order is missing required details: phone number.", "code": "missing_fields",
      "parcels": [], "warnings": [] }
  ]
}

The second consignment still exists — it needs a phone number added in Compass, or a corrected resend of just that item, before it can be finalised and labelled. summary.labels counts the labels this request drew, per label prefix ({"BY": 1} here). Your label selection rules can fall back to a second label when the first runs out, so more than one prefix appearing is worth noticing: it may be a different service at a different price. summary.draft being non-zero is what your integration should alert on; 200 alone tells you nothing about whether every item succeeded.

Result codes

Every DRAFT or REJECTED result carries a reason (text for a person, which may be reworded) and a code (stable, for your code to branch on). New codes may be added; treat one you don't recognise like needs_review (DRAFT) or unexpected_failure (REJECTED). A result replayed from a request stored before codes were introduced may have a reason and no code.

Error catalogue

Every error response — every one, with no exceptions — is application/json, shaped {"error": "<code>", "detail": "<message>"} (the label endpoint's 422 adds a failures array — see below). Treat error as the stable value to branch your code on; detail is for a human, and its wording may change.

Carrier failure codes (422)

For address_rejected, fields lists the address fields the carrier queried, when it said which, and detail then ends with a sentence naming them — for example “The carrier queried: City, Postcode / Eircode.” When a field is longer than the carrier allows, the sentence says so instead — “The carrier allows at most 40 characters in: Address line 2.” For parcel_rejected, fields lists the parcel fields the carrier refused — today always weight. For every other code, and when the carrier didn't say, fields is an empty array. Each value corresponds to a field in your request:

Migrating from Scurri

This API adopts Scurri's Create Consignment field names and envelope shape wherever a direct Enigma equivalent exists, so most of a migration is a base-URL and credential change rather than a rewrite. Three differences are worth knowing about before you send your first live batch:

1. contact_number is effectively mandatory. Scurri treats it as optional. Here, a consignment submitted without a phone number is not rejected — it is created and finalised up to the point of needing that field, then parked in DRAFT for someone to complete in Compass. If your existing integration doesn't always send a phone number, you will start seeing a steady trickle of DRAFT results with "code": "missing_fields" (reason "This order is missing required details: phone number.") where you previously saw success. Backfill the field at source if you can; it is the single most common reason a consignment doesn't come straight through.
2. Your system can still choose the label per consignment, once it's set up. If your Scurri integration picks the service for each shipment in service_id (or shipping_method), add each value it sends in Compass, under Integrations → API access → Service and warehouse values, and customer service links each one to a label. From then on a consignment sending that value gets that label, or is held as a DRAFT with the reason if the label can't be used; it is never quietly sent on another one (see Values that choose the label). A value you haven't added, or no value at all, is routed by your account's label selection rules, the same rules that route Compass and CSV imports, so an integration that sends a fixed or leftover value keeps working unchanged. carrier itself isn't read unless customer service sets it up as a value field; until then it is accepted with a warning, not an error.
3. The batch cap is 50, not Scurri's 50,000. Scurri's manifest call doesn't return allocated labels, so it can accept a huge batch and process it asynchronously. This API returns real label numbers in the same response, so each item does real work — validation, rule resolution, a label draw, and for some destinations a live carrier call — before it can reply. If your current integration pushes very large batches in one call, split them into batches of 50 or fewer.

Everything else Scurri sends that has no Enigma equivalent — customs blocks, custom fields, pick-up/drop-off store codes, and so on — is accepted and ignored with a warning, not rejected. You can point an existing Scurri payload builder at this API essentially unmodified and get a working integration on day one; the field reference above tells you exactly what each field does here so you can clean up the payload at your own pace afterwards.

Change history

Every change to this reference since v1.2, newest first. Each entry says what changed in the API, or that only the wording did, and links to the section it affects.