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

# Applicants & KYC

> Onboard end-users and verify their identity.

An **applicant** is a person or business you want to issue cards to. Every applicant passes **tenant KYC** (your approval) and **issuer KYC** (registered with the card program) before cards can be issued.

<Card title="Full KYC integration guide" icon="shield-check" href="/guides/kyc-integration">
  Step-by-step flows for Apocor-hosted verification and bring-your-own identity (BYOK), share tokens, and troubleshooting.
</Card>

## Lifecycle

```mermaid theme={null}
flowchart LR
  P[PENDING] -->|verify| R{Tenant KYC}
  R -->|approved| A[APPROVED]
  R -->|manual review| V[REVIEW]
  R -->|rejected| X[REJECTED]
  A --> I[Issuer KYC]
  I --> CH[Cardholder + cards]
```

| Status     | Meaning                   |
| ---------- | ------------------------- |
| `PENDING`  | Created, not yet verified |
| `APPROVED` | Your KYC passed           |
| `REVIEW`   | Held for manual review    |
| `REJECTED` | Verification failed       |

| Issuer field      | Meaning                                                             |
| ----------------- | ------------------------------------------------------------------- |
| `issuerKycStatus` | Progress on the card program (`PENDING` → `SUBMITTED` → `APPROVED`) |
| `issuerKycReady`  | `true` when cards can be issued                                     |

## Create an applicant

```bash cURL theme={null}
curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "type": "PERSON",
    "email": "jane@example.com",
    "data": {
      "firstName": "Jane",
      "lastName": "Doe",
      "country": "US",
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  }'
```

Include a full **residential address** with `state` (or subdivision). The card program copies the verified KYC address onto the cardholder — **state of birth alone is not sufficient** for card issuance.

Use the returned `id` as `externalUserId` when running your own identity provider (BYOK).

## Verify identity

See the [KYC integration guide](/guides/kyc-integration) for complete flows. Quick reference:

| Integration                | Start here                                                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Apocor-hosted widget       | `POST /v1/applicants/{id}/kyc-session`                                                                                |
| Your own identity provider | `POST /v1/applicants/{id}/kyc-share` with a share token                                                               |
| Poll / sandbox             | `POST /v1/applicants/{id}/submit` — syncs tenant KYC and triggers issuer handoff                                      |
| Poll issuer only           | `GET /v1/applicants/{id}/kyc-status` — refreshes `issuerKycStatus` / `issuerKycReady` without submitting share tokens |

<Tip>In sandbox with mock KYC, `status` may be `APPROVED` while `issuerKycReady` stays false. Use hosted verification or BYOK share tokens for live issuer testing.</Tip>

Once `status` is `APPROVED` **and** `issuerKycReady` is `true`, create a [cardholder](/concepts/cards) and issue cards.