Quickstart

This walks the management-company flow end to end: list your vessels → list your fleet → look up a crew member → read their profile, documents, and compliance, and download a document. Every v1 read authenticates with your API key as a Bearer token over TLS and is not signed, so each call carries the same Authorization header and nothing more (see Authentication).

Get your credentials

CrewPass issues you a partner API key (cpk_live_* and cpk_test_*). Keep it server-side.

export CPK_KEY="cpk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export BASE="https://partners.crewpass.co.uk"

Confirm who you are

GET /api/v2/partners/me returns your identity and granted scopes. It’s the first call any partner makes.

cURL

curl -sS "$BASE/api/v2/partners/me" -H "Authorization: Bearer $CPK_KEY"

Response

{
  "partner_id": "prt_123",
  "display_name": "Example Fleet Management",
  "partner_type": "customer",
  "status": "active",
  "mode": "live",
  "subscription_plan": "management",
  "granted_scopes": ["crew:compliance:read", "crew:documents:read", "crew:documents:download", "crew:profile:read", "crew:profile:full:read", "crew:status:read", "vessels:fleet:read"]
}

List your vessels

GET /api/v2/employers/me/vessels returns the vessels on your account.

cURL

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

Response

{
  "items": [
    { "vessel_id": "ves_abc", "vessel_name": "M/Y Example", "imo": "9780987", "mmsi": "232003200", "flag_state": "Cayman Islands", "vessel_type": "M/Y" }
  ]
}

List your fleet

GET /api/v2/employers/me/fleet returns every crew member on your vessels, their verification + background-check status, and a count of documents expiring soon.

Python

import httpx

r = httpx.get(
    f"{BASE}/api/v2/employers/me/fleet",
    params={"include_documents_expiring_within_days": 30},
    headers={"Authorization": f"Bearer {CPK_KEY}"},
)
print(r.json())

Response

{
  "items": [
    {
      "crew_unique_id": "crew_001",
      "name": "A. Crew",
      "vessel_id": "ves_abc",
      "vessel_name": "M/Y Example",
      "role": "Chief Engineer",
      "status": "active",
      "background_check_status": "completed",
      "documents_expiring": 1,
      "as_of": "2026-06-08T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "expiring_within_days": 30
}

Paginate with ?cursor=<next_cursor>&limit=50 (max limit 200). status and background_check_status appear only when crew:status:read is effective for that crew member.

Look up a crew member by email

If you hold crew by email, resolve to a crew_unique_id.

cURL

curl -sS "$BASE/api/v2/employers/me/crew/lookup" \
  -H "Authorization: Bearer $CPK_KEY" -H "Content-Type: application/json" \
  -d '{"email":"crew@example.com"}'

A crew member not on one of your vessels returns 404 — you can never enumerate the wider CrewPass user base.

Read profile, documents, and compliance

With a crew_unique_id, read the detail (the GETs carry only the Bearer header; the compliance check is a read-only POST with a JSON body):

cURL

H=(-H "Authorization: Bearer $CPK_KEY")

# Profile (identity fields included when crew:profile:full:read is effective)
curl -sS "$BASE/api/v2/employers/me/crew/crew_001/profile" "${H[@]}"

# Documents (issuer + verification_status)
curl -sS "$BASE/api/v2/employers/me/crew/crew_001/documents" "${H[@]}"

# Compliance snapshot (POST with body) — role / STCW / medical breakdown
curl -sS "$BASE/api/v2/employers/me/crew/crew_001/compliance-checks" \
  -H "Authorization: Bearer $CPK_KEY" -H "Content-Type: application/json" -d '{}'

Download a document file

GET …/documents/{document_id}/download returns a short-lived, CrewPass-hosted link (never a raw storage URL). Follow download_url to stream the file.

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"
}

Next steps

Now dive into a capability:

See your crew · Read a profile
Documents & downloads · Check compliance
Webhooks — get notified instead of polling.
Errors — every error code and how to handle it.

Get started

Guides

Webhooks

Reference

Next steps

​Next steps

Next steps