> ## 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.

# Quickstart

> Go from credentials to reading a crew member's documents in 15 minutes.

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](/authentication)).

<Steps>
  <Step title="Get your credentials">
    CrewPass issues you a partner API key (`cpk_live_*` and `cpk_test_*`). Keep it
    server-side.

    ```bash theme={null}
    export CPK_KEY="cpk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
    export BASE="https://partners.crewpass.co.uk"
    ```
  </Step>

  <Step title="Confirm who you are">
    `GET /api/v2/partners/me` returns your identity and granted scopes. It's the
    first call any partner makes.

    ```bash cURL theme={null}
    curl -sS "$BASE/api/v2/partners/me" -H "Authorization: Bearer $CPK_KEY"
    ```

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

  <Step title="List your vessels">
    `GET /api/v2/employers/me/vessels` returns the vessels on your account.

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

    ```json Response theme={null}
    {
      "items": [
        { "vessel_id": "ves_abc", "vessel_name": "M/Y Example", "imo": "9780987", "mmsi": "232003200", "flag_state": "Cayman Islands", "vessel_type": "M/Y" }
      ]
    }
    ```
  </Step>

  <Step title="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 Python theme={null}
    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())
    ```

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

  <Step title="Look up a crew member by email">
    If you hold crew by email, resolve to a `crew_unique_id`.

    ```bash cURL theme={null}
    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.
  </Step>

  <Step title="Read profile, documents, and compliance">
    With a `crew_unique_id`, read the detail (the `GET`s carry only the Bearer
    header; the compliance check is a read-only `POST` with a JSON body):

    ```bash cURL theme={null}
    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 '{}'
    ```
  </Step>

  <Step title="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.

    ```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"
    }
    ```
  </Step>
</Steps>

## Next steps

Now dive into a capability:

* [See your crew](/guides/crew) · [Read a profile](/guides/profiles)
* [Documents & downloads](/guides/documents) · [Check compliance](/guides/compliance)
* [Webhooks](/webhooks) — get notified instead of polling.
* [Errors](/errors/index) — every error code and how to handle it.