Validate a courier with one API.

Start here

Register as a business with your Companies House number. Sandbox keys are available at once. Live keys after KYB and a signed partner DPA. Keys are shown once — store them in a secrets manager. Never ship a key in a browser, driver app, or git repository.

Authenticate

Partner API routes under /api/v1 use the API key. The signed-in business hub uses a user session and is not for server-to-server calls. The Courier Passport iOS and Android apps use /api/app/v1 with a driver JWT — never ship a partner key in a native app.

Authorization: Bearer cdp_test_00000000_your_sandbox_key

Request consent

The driver shares a number, QR, or link. You then request access. They approve on their phone. A lookup without a live consent returns 403. Incomplete applications are not passports — you cannot consent against a number that has not been issued.

curl -sS https://api.courierpassport.com/api/v1/consents \
  -H "Authorization: Bearer cdp_test_00000000_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"passport_number":"CP-UK-7H3M-K2NQ-W"}'

Response 201 (or the existing row): { "id": "018f3d4a-9c2e-7b11-8a4d-6f2c1b0a9e88", "status": "pending" }. Poll the lookup after the driver approves, or wait for your product UI. Status granted means you may look up.

Look up a passport

Re-evaluate on every call. Do not cache valid for days. Subscribe to webhooks for lapses between lookups. The public QR page is not a substitute for this API — it never tells an anonymous scanner whether the passport is still valid.

curl -sS https://api.courierpassport.com/api/v1/passports/CP-UK-7H3M-K2NQ-W \
  -H "Authorization: Bearer cdp_test_00000000_your_sandbox_key" \
  -H "Accept: application/json"

{
  "passport_number": "CP-UK-7H3M-K2NQ-W",
  "status": "valid",
  "issued_at": "2026-09-15T12:00:00+00:00",
  "valid_until": "2026-12-15T12:00:00+00:00",
  "driver": { "legal_name": "Alex Driver" },
  "checks": {
    "identity": { "label": "Identity", "status": "passed", "expires_at": "...", "evidence_strength": "provider", "result_band": null },
    "insurance": { "label": "Courier van insurance", "status": "passed", "expires_at": "...", "evidence_strength": "document", "result_band": null }
  }
}

How to treat status

• passport.issued
• passport.expiring
• passport.expired
• passport.revalidated
• passport.suspended
• consent.revoked

{
  "event": "passport.expired",
  "passport_number": "CP-UK-7H3M-K2NQ-W",
  "status": "expired",
  "occurred_at": "2026-09-15T12:00:00+00:00"
}

import crypto from "node:crypto";

const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
const header = request.headers.get("x-courier-passport-signature") ?? "";
if (
  expected.length !== header.length ||
  !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))
) {
  throw new Error("Invalid webhook signature");
}

Errors and limits

Error bodies are { "error": "…" }. Unknown passport numbers on lookup return not_issued rather than 404, so you cannot probe the directory.