Skip to main content
KYC endpoints are called by your backend with partner credentials (Bearer API key or HMAC), never with an end-user JWT. There are two modes: document lookup (100% via API, using only the document number, no images) and full onboarding sessions (the API returns a webViewUrl your app opens in a webview for the provider to capture document, selfie, and liveness).
KYC runs on a configured provider (BigDataCorp is active; ZKPassport is the future target). If no provider is configured on the instance, calls return 503 at call time.
Access gate: the KYC gate is binary. Only kycStatus === APPROVED unlocks the payment operations (cash-out, cash-in). There are no KYC levels or per-level limits. The gate is enforced on the payment routes, not on the KYC routes themselves.
All KYC endpoints are mounted under /api/v1/users/kyc.

​
Document lookup and verify

POST /api/v1/users/kyc/lookup returns the registry data for a document; POST /api/v1/users/kyc/verify returns a validity check. Both take the same body.
​
string
required
Partner credentials: Bearer sk_live_... or the HMAC header.
​
string
required
One of CPF, CNPJ, RG, PASSPORT, SSN, DNI, CURP, RUT, CC, NIT, OTHER.
​
string
required
The document number (minimum 3 characters).
​
string
required
ISO 3166-1 alpha-2 country code, for example BR or US.
A document not found returns 404. A provider failure returns 502.

​
Onboarding sessions

​
Start an individual (PF) session

POST /api/v1/users/kyc/sessions/natural-person
​
string
required
The user’s id in your system (1 to 128 chars).
​
string
required
CPF (11 to 14 chars).
​
string
required
Full legal name.
​
string
required
Date of birth.
​
string
required
Mother’s name.
​
string
required
Contact email.
​
boolean
required
Whether the person is a politically exposed person (PEP).
​
string
default:"BR"
ISO 3166-1 alpha-2 country code.
​
object
Optional address (postalCode, street, number, neighborhood, city, state).
​
string
Optional phone number.

​
Start a company (PJ) session

POST /api/v1/users/kyc/sessions/legal-person
​
string
required
The company’s id in your system.
​
string
required
CNPJ (14 to 18 chars).
​
string
required
Legal business name.
​
string
required
Trading name.
​
string
required
One of MEI, EI, EIRELI, LTDA, SA, SLU.
​
string
required
Contact phone.
​
string
required
Business email.
​
object
required
The company address (postalCode, street, number, neighborhood, city, state).
​
array
required
One or more owners, each with ownerType (PARTNER, LEGAL_REPRESENTATIVE, or BOTH), documentNumber, fullName, birthDate, motherName, phoneNumber, email, and address.

​
Manage sessions

​
list
List the partner’s sessions. Query: limit (1 to 200), status, externalUserId.
​
lookup
Get a session by id.
​
refresh
Force a status refresh from the provider.
​
reopen
Get a fresh documentoscopy webViewUrl, reopening the session if it expired.
​
status
The latest session for one of your users. Returns hasSession: false when none exists.

​
Session status

A session moves through these statuses (also delivered as KYC_* webhooks):
Get notified of status changes via the KYC_* webhooks, or poll GET /api/v1/users/kyc/sessions/:sessionId. The session payload never exposes the raw document hash or the provider’s raw response.