Identity verification (KYC)

Before you can issue a card, every applicant must pass two checks. Apocor orchestrates both — you never integrate with the card program or identity vendors directly.

Layer	Who decides	API signal
Tenant KYC	You (the integrator)	`status` → `APPROVED`
Issuer KYC	The card program behind Apocor	`issuerKycReady` → `true`

status: APPROVED alone is not enough to issue cards. You must also wait for issuerKycReady: true. Card issuance returns ISSUER_KYC_INCOMPLETE otherwise.

Choose an integration

Option	When to use	You send
A — Hosted widget	You do not run an identity provider	Nothing — Apocor hosts the widget
B — BYOK share token	You already verify users in your own provider	A short-lived share token
C — Direct document upload	You collect ID images yourself and do not use an identity-provider widget	Identity fields + ID front / back / selfie

Options A and B never send passports or selfies to Apocor. The identity provider issues a share token; Apocor forwards that token to the card program. Option C is the exception: you upload JPEG/PNG/WEBP/PDF images to a short-lived URL. Apocor stores them only long enough to submit them to the card program.

Get your integration settings

cURL

curl -s 'https://sandbox.apocor.ai/v1/kyc/config' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "data": {
    "hostedVerificationAvailable": true,
    "shareVerificationAvailable": true,
    "issuerDirectAvailable": true,
    "shareRecipientId": "celeriz.com_139320",
    "sumsubWebhookMode": "apocor",
    "sumsubWebhookUrl": "https://api.apocor.ai/v1/webhooks/sumsub-sandbox",
    "sandboxWebhookUrls": {
      "sumsub": "https://api.apocor.ai/v1/webhooks/sumsub-sandbox",
      "interlace": "https://api.apocor.ai/v1/webhooks/interlace-sandbox",
      "dynamic": "https://api.apocor.ai/v1/webhooks/dynamic-sandbox"
    },
    "verificationSync": "Register sandbox Sumsub at POST /v1/webhooks/sumsub-sandbox; webhooks auto-sync tenant KYC and queue issuer handoff"
  }
}

Field	Meaning
`hostedVerificationAvailable`	You can use `POST /v1/applicants/{id}/kyc-session` and embed Apocor’s hosted widget
`shareVerificationAvailable`	BYOK share tokens are accepted via `kyc-share`
`issuerDirectAvailable`	Direct document KYC is available via `POST /v1/applicants/{id}/kyc-direct`
`shareRecipientId`	Apocor’s Sumsub client id — use as the share-token recipient in your identity provider (BYOK only). Never use the card-program or upstream partner id.
`sumsubWebhookMode`	`apocor` = Core API `/v1/webhooks/sumsub` (target); `seismic` = legacy Railway seismic-cards
`sumsubWebhookUrl`	Exact URL to register in the Sumsub dashboard for this environment

Test vs live (same host): both use https://api.apocor.ai. Test keys get sumsubWebhookUrl → /v1/webhooks/sumsub-sandbox; live keys → /v1/webhooks/sumsub. Register the Sumsub sandbox app against the sandbox path and the Sumsub production app against the live path.

Sumsub webhooks: use the URL from GET /v1/kyc/config (sumsubWebhookUrl). After the hosted widget completes, Sumsub webhooks update tenant status and queue issuer handoff automatically; POST /v1/applicants/{id}/submit is a fallback. Poll GET …/kyc-status for issuer progress. See Webhooks.

Option A — Apocor-hosted verification

Best when you don’t run your own Sumsub (or similar) account. Apocor hosts the widget and handles issuer handoff automatically.

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

Start a verification session

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-session' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response includes accessToken (for embedding the WebSDK) and verificationUrl (a direct Sumsub link you can email or open in a browser). externalUserId is the Apocor applicant id.

User completes the widget

When verification succeeds in the widget, call POST /v1/applicants/{id}/submit to sync tenant status and queue issuer handoff (returns immediately — no long HTTP wait). With SUMSUB_WEBHOOK_MODE=apocor, Sumsub also posts to POST /v1/webhooks/sumsub, which triggers the same background handoff when review is GREEN.

Confirm issuer readiness

cURL

curl -s 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-status' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Poll until issuerKycReady is true (issuer handoff runs in the background worker; issuer webhooks can also advance status). Then create a cardholder and issue a card.

POST /v1/applicants/{id}/submit returns as soon as tenant KYC is synced. Do not expect issuerKycReady: true in the same response — poll GET …/kyc-status every few seconds until ready.

Option B — Bring your own identity provider (BYOK)

Best for regulated companies that already run their own Sumsub (or compatible) environment. You never use Apocor’s hosted widget.

Create an applicant in Apocor

Save the returned id — you will use it as externalUserId in your identity provider.

Verify the user in your provider

Run your existing KYC flow. Set externalUserId to the Apocor applicant id so records stay linked.

Generate a share token

Call your provider’s share-token API with:

Applicant id — from your provider
Recipient — shareRecipientId from GET /v1/kyc/config (Apocor’s id, not the card issuer)

Example (Sumsub):

POST /resources/accessTokens/-/shareToken?applicantId={id}&forClientId={shareRecipientId}

Apocor imports the shared verification and forwards it to the card program internally. The token expires quickly (typically ~10 minutes). Generate it immediately before calling Apocor.

Submit the token to Apocor

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-share' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "sumsub_share_token": "YOUR_SHARE_TOKEN",
    "kyc_vendor_ref": "your-provider-applicant-id",
    "status": "APPROVED"
  }'

Field	Required	Description
`sumsub_share_token`	Yes	Short-lived share token from your provider
`kyc_vendor_ref`	No	Your provider’s applicant id (stored internally)
`status`	Recommended	Set to `APPROVED` to attest verification in the same request

Poll until ready

cURL

curl -s 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-status' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Issue cards only when issuerKycReady is true.

BYOK tenants do not need Apocor-hosted verification credentials. They only need an Apocor API key and the shareRecipientId from /v1/kyc/config.

Option C — Direct document upload

Best when you already collect ID images in your own app and do not run an identity-provider widget. Confirm issuerDirectAvailable is true on GET /v1/kyc/config before starting.

Direct KYC requires a live card-program environment and document storage. It is not available on mock/sandbox-only keys. Check issuerDirectAvailable first.

Required documents:

Category	When
`id_front`	Always
`selfie`	Always
`id_back`	Required unless `idType` is `PASSPORT`

Accepted files: JPEG, PNG, WEBP, or PDF, 8 MB or smaller. The PUT URL expires in 300 seconds.

Create an applicant

The applicant must have an email. Save the returned id.

Presign each document

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-direct/uploads' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "category": "id_front",
    "contentType": "image/jpeg",
    "size": 245760
  }'

Response includes uploadUrl and key. Repeat for selfie and id_back (if required).

PUT the file to the presigned URL

cURL

curl -s -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/jpeg' \
  --data-binary @id_front.jpg

Content-Type on the PUT must match the contentType you presigned.

Confirm the upload

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-direct/uploads/complete' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "category": "id_front",
    "s3Key": "KYC_DIRECT_KEY_FROM_STEP_2",
    "contentType": "image/jpeg",
    "fileName": "id_front.jpg"
  }'

Submit identity fields

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-direct' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1990-04-12",
    "gender": "F",
    "nationality": "US",
    "nationalId": "A12345678",
    "idType": "PASSPORT",
    "issueDate": "2020-01-15",
    "expiryDate": "2030-01-14",
    "phoneCountryCode": "1",
    "phoneNumber": "4155550100",
    "ssn": "123456789",
    "address": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "postalCode": "10001"
    }
  }'

idType must be one of: CN-RIC, PASSPORT, HK-HKID, DLN, Government-Issued ID Card, EU Residency Permit, UAE Residency Permit. gender is M or F. Dates are YYYY-MM-DD. US addresses require a 9-digit ssn.

Poll until ready

cURL

curl -s 'https://sandbox.apocor.ai/v1/applicants/app_abc123/kyc-status' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Issue cards only when issuerKycReady is true.

Applicant response fields

Every applicant includes white-labeled issuer fields:

{
  "data": {
    "id": "app_abc123",
    "status": "APPROVED",
    "issuerKycStatus": "SUBMITTED",
    "issuerKycReady": false
  }
}

`issuerKycStatus`	Meaning
`PENDING`	Issuer account exists; identity not submitted yet
`SUBMITTED`	Identity forwarded (share token or direct documents); issuer processing
`APPROVED`	Issuer accepted identity — cards can be issued
`REJECTED`	Issuer declined identity
`UNKNOWN`	Could not determine status — call `kyc-status` to refresh

Endpoints summary

Method	Path	Purpose
`GET`	`/v1/kyc/config`	Integration settings + share recipient id
`POST`	`/v1/applicants`	Create applicant
`POST`	`/v1/applicants/{id}/kyc-session`	Hosted widget session (Option A)
`POST`	`/v1/applicants/{id}/submit`	Poll tenant KYC; when approved, provision issuer account and trigger handoff
`POST`	`/v1/applicants/{id}/kyc-share`	Submit BYOK share token (Option B)
`POST`	`/v1/applicants/{id}/kyc-direct/uploads`	Presign an ID document upload (Option C)
`POST`	`/v1/applicants/{id}/kyc-direct/uploads/complete`	Record an uploaded ID document (Option C)
`POST`	`/v1/applicants/{id}/kyc-direct`	Submit identity fields + docs to the card program (Option C)
`GET`	`/v1/applicants/{id}/kyc-status`	Poll issuer KYC fields only — does not submit share tokens or documents

Troubleshooting

Symptom	Likely cause	Fix
`issuerKycReady` stays `false` after mock sandbox KYC	Mock verification does not produce real share tokens	Use hosted verification, BYOK share tokens, or Option C against a live environment
`ISSUER_KYC_INCOMPLETE` on card issue	Issuer still processing or identity never submitted	Call `POST …/submit`, `kyc-share`, or `kyc-direct`, then poll `GET …/kyc-status` until `issuerKycReady` is `true`
Card issue fails with address / state error	Residential address in KYC is missing state (state of birth alone is not enough)	Re-run verification with full address including state/subdivision, then re-submit issuer handoff
Share token rejected	Wrong `shareRecipientId`, reusable KYC not enabled, or token not addressed to Apocor	Confirm `GET /v1/kyc/config` returns Apocor’s client id; ask Sumsub to enable sharing tenant → Apocor → issuer
`KYC_NOT_APPROVED` on `kyc-share`	Tenant status not approved	Include `"status": "APPROVED"` when attesting BYOK verification
`issuerDirectAvailable` is `false`	Live issuer credentials or document storage are not configured	Use Option A or B, or ask Apocor to enable direct KYC for your keys
`INVALID_REQUEST` on `kyc-direct`	Missing `id_front`/`selfie`, missing `id_back` for non-passport, or invalid `idType` / dates	Upload required documents first; send `idType` from the allowed list; dates must be `YYYY-MM-DD`

See Error codes for the full list of error.code values.

Next steps

Applicants

Applicant lifecycle and statuses

Cards

Issue cards after issuer KYC is ready

Quickstart

End-to-end sandbox walkthrough

API Reference

Try endpoints in the playground

Get started

Core concepts

Webhooks & events

Reference

Choose an integration

Get your integration settings

Option A — Apocor-hosted verification

Option B — Bring your own identity provider (BYOK)

Option C — Direct document upload

Applicant response fields

Endpoints summary

Troubleshooting

Next steps

Applicants

Cards

Quickstart

API Reference

​Choose an integration

​Get your integration settings

​Option A — Apocor-hosted verification

​Option B — Bring your own identity provider (BYOK)

​Option C — Direct document upload

​Applicant response fields

​Endpoints summary

​Troubleshooting

​Next steps

Applicants

Cards

Quickstart

API Reference

Choose an integration

Get your integration settings

Option A — Apocor-hosted verification

Option B — Bring your own identity provider (BYOK)

Option C — Direct document upload

Applicant response fields

Endpoints summary

Troubleshooting

Next steps