Documents & downloads

For any crew member on your fleet you can list their current documents — with the issuing authority, CrewPass’s verification status and a classification you can map to your own document types — 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. A document whose classification.document_class is medical (e.g. an ENG1) is included only when crew:medical:read is also effective for the crew member; otherwise it’s left out of the list and its download link 404s. 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": "document",
      "category": "STCW Modules",
      "title": "Personal Survival Techniques (A-VI/1-1)",
      "issuer": "Maritime & Coastguard Agency",
      "verification_status": "verified",
      "issue_date": "2023-03-01",
      "expiry_date": "2028-03-01",
      "document_number": "PST-12345",
      "review_status": "verified",
      "is_expired": false,
      "no_expiry": false,
      "is_current": true,
      "superseded_by": null,
      "classification": {
        "taxonomy_version": "2026-09-17.230e599f",
        "document_class": "training",
        "category_code": "stcw_training",
        "catalogue_title": {
          "id": "6916072356124cb47c6c53fd",
          "name": "Personal Survival Techniques (A-VI/1-1)"
        },
        "stcw_regulation": "VI/1",
        "stcw_codes": ["VI/1-1"],
        "level": "support",
        "is_refresher": false,
        "flag_state": "GB",
        "coc_capacities": [],
        "sources": ["document_category", "competence_profile", "catalogue"]
      }
    }
  ]
}

Each document is returned in its latest version, and only once CrewPass has finished processing it. The list leaves out documents that are still being processed, older uploads from before CrewPass’s current document processing, duplicates, and documents CrewPass has rejected or removed. Documents left out aren’t counted in a fleet’s documents_expiring total and can’t be downloaded. A new upload appears as soon as processing completes. An earlier edition of a certificate that has since been renewed is still listed, with is_current: false. What the key fields mean:

Field	Meaning
`issuer`	The authority that issued the document, such as a flag state or training provider. `null` when it isn’t known; a placeholder such as “Unknown” is never sent.
`verification_status`	CrewPass’s check on the document, taking expiry into account: `verified`, `pending` or `expired`.
`review_status`	The result of CrewPass’s review, without expiry: `verified`, `pending`, or `pending_manual_review` (waiting for a check by the CrewPass team). An expired certificate that was verified stays `verified`.
`expiry_date`	When it expires. Use it with the fleet’s `documents_expiring` count to spot renewals.
`is_expired`	`true` once `expiry_date` has passed. `null` when there is no expiry date.
`no_expiry`	`true` for a document that does not expire, `false` when it has an expiry date, and `null` when CrewPass doesn’t know. A missing `expiry_date` without `no_expiry: true` means the date wasn’t recorded, so it’s worth checking with the crew member.
`is_current` / `superseded_by`	`is_current` is `false` once a newer edition of the same certificate is on file, and `superseded_by` gives the newer document’s `document_id`. Both are `null` when CrewPass doesn’t know.
`document_number`	The document’s own reference number.
`classification`	What the document is, as codes you can map. See the next section.

2. Classify documents

The classification block tells you what a document is, using values from the published code list, so you can file it in your own system without reading the title. CrewPass builds it from what it already holds: the certificate type the document was matched to, and the crew member’s maritime competence profile, medical record and STCW record.

Field	Meaning
`document_class`	`training`, `competency`, `endorsement`, `medical`, `identity`, `travel` or `other`. Separates certificates from paperwork.
`category_code`	A finer grouping, e.g. `stcw_training`, `deck_qualifications`, `seafarer_identity`.
`catalogue_title`	The CrewPass certificate type the document was matched to: a stable `id` and its `name`. Every document of the same type has the same `id`.
`stcw_regulation` / `stcw_codes`	The STCW regulation, and the specific units the document covers. A combined basic training certificate lists `VI/1-1` to `VI/1-4`.
`level`	`management`, `operational` or `support`, where the certificate has one.
`is_refresher`	`true` for an updated proficiency (refresher) certificate.
`flag_state`	ISO 3166 alpha-2 code of the state that issued the document.
`coc_capacities`	For a certificate of competency, each capacity it grants: `stcw_regulation`, `role`, `level` and its limits (`gt_max`, `kw_max`, `power_unrestricted`, `area`, `vessel_types`).
`sources`	What the classification was built from, in order. See evidence sources.
`taxonomy_version`	The version of the code list the values come from.

A null or an empty list means CrewPass doesn’t hold that fact for the document; it never means “no”. The whole block can be null if a document can’t be classified at the moment. Treat that as unknown and fall back to title.

Mapping to your own types

Use the most specific signal first:

document_class decides where the document belongs: certificates (training, competency, endorsement) or paperwork (identity, medical, travel).
STCW training: stcw_codes with is_refresher. For example VI/1-2 with is_refresher: true is the updated proficiency in fire prevention and fire fighting.
Certificates of competency: coc_capacities, e.g. regulation II/2, role Master, gt_max: 3000, vessel_types: ["yacht"].
Everything else (short courses, specialist training): keep a one-time map keyed by catalogue_title.id.
Fall back to title only when none of the above is set.

3. 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. Classify documents

Mapping to your own types

3. Download a file

Download every document for a crew member

Next

​1. List documents

​2. Classify documents

​Mapping to your own types

​3. Download a file

​Download every document for a crew member

​Next

1. List documents

2. Classify documents

Mapping to your own types

3. Download a file

Download every document for a crew member

Next