Integration flows

Carrier Portal API — public orders integration (overview)

This describes how external systems integrate with the Carrier API order endpoints (api/v{version}/..., version 1.0). Detailed request/response shapes live in your API reference; this page explains how the pieces fit together and which flows use which endpoints.

Authentication and base URL follow your environment (e.g. API key / company policy as configured for the Carrier API). The controller applies rate limiting on these routes.

Order number is unique per your company account (the service normalizes it before comparing). Always persist the returned orderId (GUID) in your system; almost all document and follow-up calls use orderId, not the human-readable order number.

Creating or updating orders

You can integrate in two ways:

POST .../orders — Create only. Fails if an order with the same order number already exists for your company. Use when you want a strict “create once” semantics.

POST .../orders/upsert — Create or update by order number (“absorb”).

If no order exists → creates one (response flags include created and link changed when a new share link is issued).

If it exists → updates it (updated flag), unless the order is already completed (updates are rejected).

Carrier change: If the carrier on the payload differs from the stored carrier, the system assigns the new carrier and regenerates the carrier share link (link changed). If the order already has documents uploaded, changing the carrier is not allowed.

PUT .../orders/{orderId} updates an order by id; it does not allow changing the carrier (even when there are no documents).

After create or upsert, store orderId and optionally surface the Share URL from the response to operations that need the carrier-facing link.

Documents: metadata and download

GET .../orders/{orderId} — Full order, including Documents (ids, types, names, statuses, comments).

POST .../orders/query — Search/list orders (filters include status, carrier, order number pattern, loading/unloading date ranges, continuation token for paging). Each row includes documents summary same as above. Use this to find orders or restrict to “active” or other status values you care about—not required for every integration.

To download a file:

GET .../orders/{orderId}/documents/{documentId}/content — Returns the file bytes (suitable for archiving CMR, invoice, packing list, etc., depending on what was uploaded and how types are labeled).

Workflow A — Automatic pipeline (typical: act when documents are accepted)

Goal: Minimize manual steps; your system reacts when paperwork is ready/accepted.

Create or upsert the order (POST /orders or POST /orders/upsert) and save orderId.

Webhooks (planned / separate configuration): You will receive notifications according to your setup. In the common case, you only care about events when a document is accepted (or equivalent “ready” signal).

When notified (or on a poll if you combine with query), refresh order data (GET) and read Documents.

For each document you need, call .../content to download.

Optional extra step (both workflows): Your customer may need to upload an order PDF or self-billing invoice from their side. That is covered by the document upload API described in public docs (Document Upload) — POST .../orders/{orderId}/documents with multipart file and documentType.

Supporting calls (not every run): DELETE .../orders/{orderId} to remove an order; query / GET to locate or audit orders.

Workflow B — Manual confirmation in your system (review uploaded documents)

Goal: Your team or automation reviews uploads before they count as accepted.

Same create/upsert and orderId storage.

Webhooks: Configure so you are notified when new documents are uploaded (not only when accepted).

GET order to see Documents; use .../content to download and review.

POST .../orders/{orderId}/documents/{documentId}/status — Set document status to Accepted or Rejected (with optional reasoning / rejection reason per your API model). The API only allows transitions appropriate to the document’s current state (see your reference; the implementation focuses on InReview / Accepted / Rejected style states for changes).

Order-level status values in responses (e.g. InReview, Accepted, Rejected at the order layer vs document layer) align with your query filters for document-centric states where applicable—use your detailed spec for exact enum meanings.

Integration flows

Carrier Portal API — public orders integration (overview)#

Creating or updating orders#

Documents: metadata and download#

Workflow A — Automatic pipeline (typical: act when documents are accepted)#

Workflow B — Manual confirmation in your system (review uploaded documents)#

Carrier Portal API — public orders integration (overview)

Creating or updating orders

Documents: metadata and download

Workflow A — Automatic pipeline (typical: act when documents are accepted)

Workflow B — Manual confirmation in your system (review uploaded documents)