Fleetfully Staging API · v2

This document

• 200 OK → OpenApiDocument

The calling key: mode, scopes, carrier and customer

• 200 OK → Me
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

A Postman collection of this API, generated from this document

• 200 OK → PostmanCollection

List orders, newest first

Page with `cursor` until `nextCursor` is null. For an incremental sync, keep the newest `updatedAt` you have seen and ask for `updatedSince` it.

• 200 OK → OrderList
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

Create an order

The order goes through the carrier's intake checks. **201**: the order exists with its tracking number (status PENDING_REVIEW until the carrier accepts it — `order.approved` follows). `submission.status` is `processing` while the order is placed in the background (address pins, price, the carrier's auto-dispatch — usually a second or two), then `accepted`; GET /submissions/{id} or GET /orders/{trackingNumber} show it placed. **202**: it needs a dispatcher: it waits in the carrier's review queue and `submission.issues` says why; poll GET /submissions/{id} or listen for `order.created`. **200**: this order was submitted before (same `externalRef` and details) — its current state, nothing new is made. Sending an `externalRef` again with different details puts the new version in review. A body that doesn't match the schema is a 422 and nothing is stored.

Body: CreateOrderRequest

• 200 OK → SubmissionResponse
• 201 OK → SubmissionResponse
• 202 OK → SubmissionResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version, or a missing Idempotency-Key → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 409 The first request with this Idempotency-Key is still running: retry shortly → Error
• 422 The body doesn't match the schema, or the Idempotency-Key was used for a different request → Error
• 429 Rate limit exceeded → Error

One order

• 200 OK → OrderResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

Where an order stands: status, milestones, proof of delivery, the last event

• 200 OK → Tracking
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

An order's status history, oldest first (the webhook event types; undone events are left out)

• 200 OK → History
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

What became of a submitted order: being placed, accepted, in review, or rejected with the dispatcher's note

• 200 OK → SubmissionResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

Send many orders for one customer

JSON `lines` (each a BatchLine), or multipart/form-data with a CSV or XLSX `file` read with the customer's saved order-feed mapping. **202**: stored and queued — poll GET /batches/{id} (the Location header) or listen for `batch.completed`. **200**: these exact bytes were sent before for this customer — that batch, nothing new. Only the envelope is refused (**422**: unreadable, no lines, over the line or byte cap, a missing or unknown customer, no saved mapping for a file). A line that doesn't match BatchLine is kept and goes to the carrier's review queue with its reason; the rest go ahead. A line with an `externalRef` is the same order whether it comes in a batch or through POST /orders. **429**: too many open batches for the key, or its hourly line budget (Retry-After).

Body: CreateBatchRequest

• 200 OK → BatchResponse
• 202 OK → BatchResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version, or a missing Idempotency-Key → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 409 The first request with this Idempotency-Key is still running: retry shortly → Error
• 422 The body doesn't match the schema, or the Idempotency-Key was used for a different request → Error
• 429 Rate limit exceeded → Error

A batch's status and line counts

• 200 OK → BatchResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

A batch's lines, in batch order: outcome, status now, tracking number and reasons

• 200 OK → BatchLineList
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

The key's webhook endpoints

• 200 OK → WebhookList
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

Add a webhook endpoint

Returns the signing secret once. Each subscribed event is POSTed as a `WebhookPayload` (see `webhooks` below), retried with backoff until your endpoint answers 2xx.

Body: CreateWebhookRequest

• 201 OK → WebhookCreated
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version, or a missing Idempotency-Key → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 409 The first request with this Idempotency-Key is still running: retry shortly → Error
• 422 The body doesn't match the schema, or the Idempotency-Key was used for a different request → Error
• 429 Rate limit exceeded → Error

Stop sending to a webhook endpoint (it is disabled; its delivery log stays with the carrier)

• 200 OK → WebhookDisabled
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version, or a missing Idempotency-Key → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 404 Not found, or not this key's → Error
• 409 The first request with this Idempotency-Key is still running: retry shortly → Error
• 422 The body doesn't match the schema, or the Idempotency-Key was used for a different request → Error
• 429 Rate limit exceeded → Error

The sandbox's webhook inbox URL (test keys only)

Made on first use, the same URL after. Point a sandbox webhook at it (POST /webhooks) to watch signed deliveries arrive in GET /inbox before you host an endpoint. A live key is a 403.

• 200 OK → InboxResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version, or a missing Idempotency-Key → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 409 The first request with this Idempotency-Key is still running: retry shortly → Error
• 422 The body doesn't match the schema, or the Idempotency-Key was used for a different request → Error
• 429 Rate limit exceeded → Error

The sandbox inbox's newest deliveries (test keys only)

Each delivery with its event, delivery id, whether its signature verified with the sending webhook's secret, and the body as received.

• 200 OK → InboxMessages
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope, or the carrier's plan doesn't include the API → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

The calling shipper key: mode, scopes, your org and the carriers it reads now

• 200 OK → ShipperMe
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

Your shipments across every carrier you are linked to, and from your status feeds, newest first

Every carrier that accepted your link request shares the shipments for the account it chose; a paused or ended link shows nothing. Shipments your status feeds name for a carrier not on the platform are merged in (`source: "external"`, id `ext_…`) — one already matched to a linked carrier's order is listed once, as that order. Switch on `source`; `source=carrier` keeps the list to carriers' orders. Page with `cursor` until `nextCursor` is null — keep the filters the same between pages. Drafts and quotes are never shipments.

• 200 OK → ShipmentList
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error

One shipment: status, milestones, arrival window, last scan, exceptions and proof on file — or, for an `ext_…` id, its status-file updates

An `ext_…` id that has since matched a linked carrier's order answers that order (`source: "carrier"`, its own id) — use that id from then on.

• 200 OK → ShipmentResponse
• 400 A malformed request: bad JSON, an unknown Fleetfully-Version → Error
• 401 No key, or an unknown or revoked one → Error
• 403 The key lacks the scope → Error
• 404 Not found, or not this key's → Error
• 422 The query doesn't match the schema → Error
• 429 Rate limit exceeded → Error