> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewpass.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents & downloads

> List a crew member's certificates with issuer and verification status, then download the files.

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.

<Info>**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.</Info>

## 1. List documents

```bash cURL theme={null}
curl -sS "$BASE/api/v2/employers/me/crew/crew_001/documents" \
  -H "Authorization: Bearer $CPK_KEY"
```

```json Response theme={null}
{
  "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.

```bash cURL theme={null}
# 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"
```

```json Response theme={null}
{
  "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"
}
```

```bash cURL theme={null}
# 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 Python theme={null}
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)")
```

<Note>
  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.
</Note>

## Next

* [Check compliance](/guides/compliance) — which of these documents satisfy the
  role's requirements.