Applicants & KYC

An applicant is a person or business you want to issue cards to. Every applicant completes identity verification before cards can be issued — the status field is the single verdict.

Full KYC integration guide

Step-by-step flows for Apocor-hosted verification, bring-your-own identity (BYOK), and direct document upload.

Lifecycle

Status	Meaning
`PENDING`	Verification in progress (any stage)
`APPROVED`	Fully verified — cards can be issued
`REVIEW`	Application needs attention
`REJECTED`	Verification failed (terminal)

The applicant.status_changed webhook fires on every transition of this field.

Create an applicant

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "type": "PERSON",
    "email": "[email protected]",
    "data": {
      "firstName": "Jane",
      "lastName": "Doe",
      "country": "US",
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  }'

Include real firstName and lastName (Latin letters and spaces) — the issuer builds the cardholder from these and rejects empty or non-Latin names at card issuance. Also 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. For US nationality or address, include data.ssn (9 digits) before issuing a card. Hosted Sumsub KYC can approve without storing SSN on the applicant — card create will fail without it. You can also set a missing SSN later with PATCH /v1/applicants/{id} (once-write). Use the returned id as externalUserId when running your own identity provider (BYOK).

Update an applicant

cURL

curl -s -X PATCH 'https://sandbox.apocor.ai/v1/applicants/APPLICANT_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{ "data": { "ssn": "123456789" } }'

Contact fields (phone, occupation, …) can usually be updated.
ssn may be set once when missing; cannot be changed after set or after cards exist.
Identity fields (name, DOB, nationality, address) lock after issuer KYC is complete or cards exist — create a new applicant to change them.
POST /v1/cards returns 400 MISSING_SSN immediately for US applicants without SSN (does not enqueue a pending issuance).

Verify identity

See the KYC integration guide 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
Direct document upload	`POST /v1/applicants/{id}/kyc-direct/uploads` then `POST /v1/applicants/{id}/kyc-direct`
Poll / sandbox	`POST /v1/applicants/{id}/submit` — submits for verification, completes in the background
Poll status	`GET /v1/applicants/{id}/kyc-status` — refreshes and returns the current `status` without submitting share tokens

In sandbox with mock KYC, status can stay PENDING because mock verification produces no real share tokens. Use hosted verification or BYOK share tokens for full end-to-end testing. Direct document KYC (kyc-direct) needs live issuer credentials — check issuerDirectAvailable on GET /v1/kyc/config.

Once status is APPROVED, create a cardholder and issue cards.

Get started

Core concepts

Webhooks & events

Reference

Full KYC integration guide

Lifecycle

Create an applicant

Update an applicant

Verify identity

Full KYC integration guide

​Lifecycle

​Create an applicant

​Update an applicant

​Verify identity

Lifecycle

Create an applicant

Update an applicant

Verify identity