REST API

Pull carrier records, documents, and packets on demand. Bearer-token authenticated, paginated, JSON.

Base URL

https://carrierpacket.link/api/v1

Authentication

Every request needs an API key in the Authorization header. Generate keys at Embedded → API keys. We hash and store keys (never the plaintext) and show you the full value once on creation — copy it then.

curl https://carrierpacket.link/api/v1/submissions \
  -H "Authorization: Bearer cpl_a1b2c3_x9z7y…"

For quick tests you can also pass the key as a query parameter: ?api_key=cpl_…. Don't use this in production — it leaks into server logs and browser history.

IP allowlist

When you generate a key, you can optionally restrict it to specific source IPs (comma-separated, literal addresses; CIDR support is coming). Requests from any other IP get a 403 ip_not_allowed.

Tracking last use

Every successful authenticated request bumps last_used_at + last_used_ip on the key. The Embedded → API keys table surfaces both so you can audit usage and spot keys that haven't been touched in a while.

Response shape

Success

Single objects:

{ "data": { "id": 1138, "legal_name": "EVERGREEN SHIPPERS LLC", ... } }

Lists include a pagination envelope:

{
  "data": [ { ... }, { ... } ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 234,
    "has_more": true
  }
}

List endpoints accept ?page=N (1-indexed) and ?limit=N (default 50, max 200). Pagination is offset-based.

Errors

{ "error": { "code": "unauthorized", "message": "Invalid or revoked API key." } }

Submissions

A submission is one carrier signing one packet. Tenant-scoped — you only see submissions for packets you own.

List submissions

Query params: page, limit, status (1=Pending verify, 2=Verified, 3=Rejected, 4=Archived).

curl 'https://carrierpacket.link/api/v1/submissions?status=2&limit=10' \
  -H "Authorization: Bearer cpl_…"

Get a submission

curl https://carrierpacket.link/api/v1/submissions/1138 \
  -H "Authorization: Bearer cpl_…"

Sample response (truncated):

{
  "data": {
    "id": 1138,
    "packet_id": 7,
    "hashid": "8b3e4f...",
    "status": 2,
    "mc_number": "896325",
    "usdot_number": "2569360",
    "legal_name": "EVERGREEN SHIPPERS LLC",
    "phone": "+1 (509) 991-8269",
    "physical_address": "13323 N MAYFAIR LN",
    "physical_city": "SPOKANE",
    "physical_state": "WA",
    "physical_zip": "99208",
    "dispatcher_email": "dispatch@carrier.com",
    "services_provided": ["Flatbed", "Reefer"],
    "auth_fullname": "John W. Smith",
    "auth_email": "john@carrier.com",
    "signed_at": "2026-04-26 14:33:18",
    "email_verified_at": "2026-04-26 14:51:02"
  }
}

Submission fields

List documents for a submission

Returns every uploaded document tied to one submission. Each row carries a derived days_until_expiry field (null if no expires_on is set).

{
  "data": [
    {
      "id": 482,
      "doc_type": "coi",
      "original_filename": "evergreen-coi-2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 412573,
      "expires_on": "2026-09-15",
      "days_until_expiry": 142,
      "created": "2026-04-26 14:33:21"
    }
  ]
}

Documents

Cross-submission view of every document the broker has on file. Designed for renewal-tracking dashboards.

List documents

Query params:

Example: documents expiring in the next 30 days

curl 'https://carrierpacket.link/api/v1/documents?expiring_within=30&doc_type=coi' \
  -H "Authorization: Bearer cpl_…"

You get back a sorted list (soonest expiry first) with days_until_expiry on each row. Negative values mean the document is already expired.

Get a document

Document fields

Packets

List packets

Query params: page, limit, status (0=Draft, 1=Active, 2=Archived).

curl 'https://carrierpacket.link/api/v1/packets?status=1' \
  -H "Authorization: Bearer cpl_…"

Get a packet

Returns the packet metadata plus the full settings JSON (branding choices, doc-collection toggles, default lookup, etc.) and the embed_token you'd put in an iframe.

{
  "data": {
    "id": 7,
    "name": "Standard Carrier Packet",
    "slug": "standard-packet",
    "status": 1,
    "embed_token": "abc123def456...",
    "settings": {
      "fg": "#40b9c7",
      "bg": "#f7fafc",
      "filesEnabled": true,
      "docs": { "w9": true, "coi": true, "authority": true, "references": false, "ach": false, "other": true }
    },
    "signed_count": 47,
    "last_activity": "2026-04-26 14:33:18"
  }
}

Packet fields

Error handling

Every error returns the same envelope:

{ "error": { "code": "ip_not_allowed", "message": "Your IP (76.135.204.132) isn't on this key's allowlist." } }

The code field is the stable contract — integrate against that, not the human message (which we'll polish over time).

Retry strategy

For 5xx and network failures, retry with exponential backoff: 1s, 2s, 4s, 8s. Cap at 5 retries. For 4xx, don't retry — the request itself is wrong, retrying won't help.

Idempotency: every endpoint here is read-only, so retrying is safe by construction. When write endpoints ship, we'll publish an idempotency-key header.

What's coming