Documents & downloads

For any crew member on your fleet you can list their current documents — with the issuing authority and CrewPass’s verification status — and download the actual files through a short-lived, CrewPass-hosted link.

Requires crew:documents:read to list, and crew:documents:download to fetch a file. Both authenticated with your API key as a Bearer token over TLS; reads are not signed.

1. List documents

cURL

curl -sS "$BASE/api/v2/employers/me/crew/crew_001/documents" \
  -H "Authorization: Bearer $CPK_KEY"

Response

{
  "crew_unique_id": "crew_001",
  "items": [
    {
      "document_id": "doc_1",
      "type": "STCW",
      "category": "STCW Modules",
      "title": "Personal Survival Techniques",
      "issuer": "Maritime & Coastguard Agency",
      "verification_status": "verified",
      "issue_date": "2023-03-01",
      "expiry_date": "2028-03-01",
      "document_number": "PST-12345"
    }
  ]
}

Only the current, live version of each document is returned. Superseded re-uploads, soft-deleted/deduplicated rows, and documents CrewPass has rejected or removed are all excluded — they never list, never count towards a fleet’s documents_expiring total, and cannot be downloaded. What the key fields mean:

Field	Meaning
`issuer`	The issuing authority CrewPass resolved (e.g. a flag state or training school). `null` if it couldn’t be determined. Never a verification vendor.
`verification_status`	CrewPass’s check on the document: `verified`, `pending`, or `expired`. (Rejected documents are excluded from the list entirely.)
`expiry_date`	When it expires. Combine with the fleet’s `documents_expiring` count to spot renewals.
`document_number`	The certificate’s own reference number.

2. Download a file

Downloading is a two-step flow. First ask for a link; then follow it. The link is hosted on a CrewPass domain, expires in about 15 minutes, and the underlying storage location is never exposed.

cURL

# Step A — get a short-lived link
curl -sS "$BASE/api/v2/employers/me/crew/crew_001/documents/doc_1/download" \
  -H "Authorization: Bearer $CPK_KEY"

Response

{
  "document_id": "doc_1",
  "download_url": "https://partners.crewpass.co.uk/api/v2/files/eyJ…",
  "expires_at": "2026-06-08T10:15:00Z",
  "content_type": "application/pdf",
  "file_name": "PST_certificate.pdf"
}

cURL

# Step B — follow the link (no API key needed; the link itself is the credential)
curl -sSL "<download_url>" -o PST_certificate.pdf

Download every document for a crew member

A common job — pull all of someone’s certificates into your own system. List, then download each one:

Python

import httpx

auth = {"Authorization": f"Bearer {CPK_KEY}"}
base = f"{BASE}/api/v2/employers/me/crew/crew_001"
docs = httpx.get(f"{base}/documents", headers=auth).json()

for d in docs["items"]:
    link = httpx.get(
        f"{base}/documents/{d['document_id']}/download",
        headers=auth,
    ).json()
    pdf = httpx.get(link["download_url"]).content   # follow the branded link
    with open(link["file_name"], "wb") as f:
        f.write(pdf)
    print("saved", link["file_name"], f"({len(pdf)} bytes)")

Each download link is single-purpose and short-lived. If crew:documents:download isn’t enabled, or the crew member is off your fleet, you get 403 / 404 rather than a link. If the file store is briefly unreachable you get a 503 — never an unsigned storage URL.

Check compliance — which of these documents satisfy the role’s requirements.

Get started

Guides

Webhooks

Reference

1. List documents

2. Download a file

Download every document for a crew member

Next

​1. List documents

​2. Download a file

​Download every document for a crew member

​Next

1. List documents

2. Download a file

Download every document for a crew member

Next