KYC
Submit and inspect KYC for end-users. Required before on-ramp and off-ramp.
Overview
Create a subaccount for each end-user before submitting KYC. Each subaccount has its own verification.
POST /api/subaccount— create a subaccount for one end-user. Returns asubAccountId. PassaccountType: "COMPANY"to onboard a business.POST /api/kyc/document— register a document and get a one-time upload URL, or — for the selfie — a hosted liveness session. Reference the returneddocumentIdinPOST /api/kyc.POST /api/kyc— submit an individual subaccount's personal data + document ids, get back anattemptId.POST /api/kyc/import-token— reuse an existing verification through a share token and get anattemptId.POST /api/kyb— start business verification for aCOMPANYsubaccount, get back anattemptIdplus hosted form URLs.GET /api/kyc/{attemptId}— poll for the result of either a KYC or a KYB attempt (PENDING→APPROVEDorREJECTED).- Webhooks
KYC_APPROVED/KYC_REJECTED— pushed when the attempt resolves. See Webhooks.
A subaccount is allowed to transact (/api/deposit/asset, /api/wallet/payout) only after its most recent KYC attempt is APPROVED.
Subaccounts can transact for their own tax ID by default. Other beneficiaries require third-party operations to be enabled.
Subaccounts
Subaccounts have their own KYC, beneficiaries and operations. They are permanent and cannot be deleted.
A subaccount is either an individual (INDIVIDUAL, the default) verified through POST /api/kyc, or a business (COMPANY) verified through POST /api/kyb. Pick the type at creation — it cannot be changed afterwards.
POST /api/subaccount
curl --request POST \
--url https://api.hodle.com.br/api/subaccount \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{ "name": "Acme Ltda.", "accountType": "COMPANY" }'| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Label to identify the subaccount. Up to 64 chars. For a business, use the legal company name. |
accountType | string | No | INDIVIDUAL (default) or COMPANY. A COMPANY subaccount is verified via KYB, not KYC. |
email | string | No | Contact email for the subaccount. |
{ "success": true, "data": { "subAccountId": "c852df87-ac61-4259-8242-6451658dfedb" } }GET /api/subaccount
List your subaccounts. Optional name (substring filter) and cursor (pagination) query params.
curl --url "https://api.hodle.com.br/api/subaccount" \
--header "Authorization: Bearer $API_KEY"GET /api/subaccount/{subAccountId}
Fetch a single subaccount by id. Once its KYC is approved, SubAccount.accountInfo carries identityStatus: "CONFIRMED" and the verified fullName, taxId and birthdate.
curl --url "https://api.hodle.com.br/api/subaccount/c852df87-ac61-4259-8242-6451658dfedb" \
--header "Authorization: Bearer $API_KEY"Flow
- Collect the user's data and the ID photo in your UI.
POST /api/kyc/documentwithdocumentType: "ID"(orDRIVERS-LICENSE/PASSPORT) — upload the image to the returned URL. See Uploading documents.POST /api/kyc/documentwithdocumentType: "SELFIE-FROM-LIVENESS"— send the user to the returnedlivenessUrlto record the selfie. See Liveness selfies.POST /api/kyc— submit the personal data referencing the twodocumentIds. Hodle returns anattemptId.- Wait for either the
KYC_APPROVED/KYC_REJECTEDwebhook or pollGET /api/kyc/{attemptId}every ~30 seconds. - Once
status: APPROVED, the user can on-ramp / off-ramp.
Typical resolution is under 2 minutes for clean submissions; manual review can take up to 24h.
To reuse an existing verification, replace steps 1–4 with POST /api/kyc/import-token. Wait for approval before transacting.
Uploading documents
Upload the identity document and have the user complete a hosted liveness selfie. Reference both returned documentIds when submitting KYC.
1. Register the document — POST /api/kyc/document
curl --request POST \
--url https://api.hodle.com.br/api/kyc/document \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{ "subAccountId": "c852df87-...", "documentType": "SELFIE-FROM-LIVENESS" }'| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The subaccount the document belongs to. |
documentType | string | Yes | SELFIE-FROM-LIVENESS for the required liveness selfie; ID, DRIVERS-LICENSE or PASSPORT for the identity document. Plain SELFIE uploads cannot be used for KYC. |
isDoubleSided | boolean | No | Set true for documents with a back side (e.g. most national IDs). Returns a second URL. |
redirectUrl | string | No | SELFIE-FROM-LIVENESS only. Where the hosted capture page sends the user once the verification is done: an https:// page or an app deep link (yourapp://kyc-done). http:, javascript:, data: and similar schemes answer 400. See Returning to your app. |
{
"success": true,
"data": {
"documentId": "doc_b21...",
"uploadUrlFront": "https://uploads.hodle.com.br/...",
"uploadUrlBack": "https://uploads.hodle.com.br/..."
}
}uploadUrlBack is only present when isDoubleSided is true.
Liveness selfies
For SELFIE-FROM-LIVENESS, the response contains a hosted capture URL instead of upload URLs. Skip upload steps 2 and 3 below.
{
"success": true,
"data": {
"documentId": "doc_b21...",
"sessionId": "0ee149a1-...",
"livenessUrl": "https://app.hodle.com.br/liveness/doc_b21...#sessionId=0ee149a1-...&token=eyJhbGciOi...",
"validateLivenessToken": "eyJhbGciOi...",
"livenessIdentityPoolId": "eu-west-1:...",
"livenessRegion": "eu-west-1"
}
}- Open the returned
livenessUrlon a device with a camera, using a full-page redirect, new window or mobile deep link. Use the URL unchanged; the capture page cannot be embedded in aniframe. - Poll
GET /api/kyc/document/{documentId}?subAccountId=...untilready: true. - Send that
documentIdasuploadedSelfieIdinPOST /api/kyc.
Create the document just before capture: sessions and tokens expire. If the token expires, register a new liveness document.
Returning to your app
Pass redirectUrl when you register the liveness document to bring the user back after the capture:
curl --request POST \
--url https://api.hodle.com.br/api/kyc/document \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{ "subAccountId": "c852df87-...", "documentType": "SELFIE-FROM-LIVENESS", "redirectUrl": "yourapp://kyc-done" }'The returned livenessUrl already carries it (...&redirectUrl=yourapp%3A%2F%2Fkyc-done); open it unchanged. When the verification is done, the page shows "Verificação concluída", sends the user to redirectUrl after about two seconds and offers a "Voltar para o app" button in case the browser blocks the automatic redirect. Without redirectUrl, the page only tells the user to go back to where they started.
Reaching redirectUrl does not mean the selfie is approved: still poll readiness (step 2) before submitting KYC.
The URL and session fields depend on your account's capture flow. If the detector fields are present, you can use Liveness capture in your own app. Otherwise, use livenessUrl. With second verification enabled, the hosted page runs two captures.
2. Upload the image
PUT the raw image bytes to each URL. The URL is one-time and expires shortly.
curl --request PUT \
--url "$UPLOAD_URL_FRONT" \
--header "If-None-Match: *" \
--header "Content-Type: image/jpeg" \
--data-binary "@document-front.jpg"Accepted content types: image/jpeg, image/png, application/pdf.
3. Check readiness — GET /api/kyc/document/{documentId}
Pass the required subAccountId query parameter.
curl --url "https://api.hodle.com.br/api/kyc/document/doc_b21...?subAccountId=c852df87-..." \
--header "Authorization: Bearer $API_KEY"{
"success": true,
"data": {
"documentId": "doc_b21...",
"ready": true,
"documentType": "SELFIE-FROM-LIVENESS",
"uploadStatusFront": "COMPLETED"
}
}| Field | Description |
|---|---|
ready | true when upload or capture is complete. KYC still requires the matching document type. |
uploadStatusFront | WAITING-UPLOAD, PENDING, PROCESSING, COMPLETED or EXPIRED. May be omitted. |
uploadErrorFront | Present only when the upload failed. Same pair exists for ...Back. |
Liveness capture in your own app
If the document response includes the detector fields below, you can render
AWS Amplify's FaceLivenessDetector in your app. Read the session, pool and region from every response; they can vary by session. If these fields are absent, use the hosted livenessUrl.
Session fields
| Field | Use it for |
|---|---|
sessionId | The detector's sessionId. |
livenessIdentityPoolId | The Cognito guest identity pool that issues credentials for the session. |
livenessRegion | The detector's region, and the Cognito region. |
validateLivenessToken | Confirming the capture (and the credentials endpoint below). |
Credentials
Get guest credentials from the pool in the response — two public calls, no API key:
const cognito = async (target: string, body: object) => {
const response = await fetch(`https://cognito-identity.${livenessRegion}.amazonaws.com/`, {
method: 'POST',
headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': `AWSCognitoIdentityService.${target}`,
},
body: JSON.stringify(body),
})
return response.json()
}
const credentialProvider = async () => {
const { IdentityId } = await cognito('GetId', { IdentityPoolId: livenessIdentityPoolId })
const { Credentials } = await cognito('GetCredentialsForIdentity', { IdentityId })
return {
accessKeyId: Credentials.AccessKeyId,
secretAccessKey: Credentials.SecretKey,
sessionToken: Credentials.SessionToken,
expiration: new Date(Credentials.Expiration * 1000),
}
}Credentials are short-lived and scoped to the capture session.
Alternative — POST /api/public/liveness/credentials. Send the validateLivenessToken
and we return the credentials and the region for that session:
curl --request POST \
--url https://api.hodle.com.br/api/public/liveness/credentials \
--header "Content-Type: application/json" \
--data '{ "validateLivenessToken": "eyJhbGciOi..." }'{
"success": true,
"data": {
"accessKeyId": "ASIA...",
"secretAccessKey": "...",
"sessionToken": "...",
"expiration": "2026-09-26T12:15:00.000Z",
"region": "us-east-1"
}
}This endpoint needs no API key and allows browser requests from any origin. It is rate limited per IP.
Rendering the detector
<FaceLivenessDetectorCore
sessionId={sessionId}
region={livenessRegion}
config={{ credentialProvider }}
onAnalysisComplete={confirmCapture}
/>Confirming the capture
When onAnalysisComplete fires, confirm the capture with the same token:
curl --request POST \
--url https://api.hodle.com.br/api/public/liveness/validate \
--header "Content-Type: application/json" \
--data '{ "validateLivenessToken": "eyJhbGciOi..." }'No API key is required. Confirm from your browser or server, then poll document readiness before using documentId as uploadedSelfieId.
Retrying a capture
If validation fails because the capture was not approved or confidence was too low, ask the user to improve lighting and remove face obstructions. For captures that support it, request a new session with the same token and documentId:
curl --request POST \
--url https://api.hodle.com.br/api/public/liveness/hodle/session \
--header "Content-Type: application/json" \
--data '{ "token": "eyJhbGciOi..." }'The response is { "success": true, "data": { "sessionId": "..." } }. Remount the detector with the new sessionId, then validate again. A completed document returns alreadyCompleted: true. Retry tokens last 30 minutes. If the token has expired or the capture does not support this endpoint, register a new liveness document. The hosted page handles capture retries.
POST /api/kyc
Request
curl --request POST \
--url https://api.hodle.com.br/api/kyc \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"subAccountId": "5b9f1a83b6b7c2b001f3c9e21",
"fullName": "João da Silva",
"dateOfBirth": "1990-01-15",
"countryOfTaxId": "BRA",
"taxIdNumber": "12345678900",
"email": "joao@example.com",
"phone": "+5511999990000",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"zipCode": "01000-000",
"streetAddress": "Av. Paulista, 1000",
"uploadedSelfieId": "sel_8f3...",
"uploadedDocumentId": "doc_b21..."
}'const res = await fetch('https://api.hodle.com.br/api/kyc', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
subAccountId,
fullName: 'João da Silva',
dateOfBirth: '1990-01-15',
countryOfTaxId: 'BRA',
taxIdNumber: '12345678900',
email: 'joao@example.com',
country: 'BRA',
state: 'SP',
city: 'São Paulo',
zipCode: '01000-000',
streetAddress: 'Av. Paulista, 1000',
uploadedSelfieId,
uploadedDocumentId,
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/kyc",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"subAccountId": sub_account_id,
"fullName": "João da Silva",
"dateOfBirth": "1990-01-15",
"countryOfTaxId": "BRA",
"taxIdNumber": "12345678900",
"email": "joao@example.com",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"zipCode": "01000-000",
"streetAddress": "Av. Paulista, 1000",
"uploadedSelfieId": uploaded_selfie_id,
"uploadedDocumentId": uploaded_document_id,
},
)
data = res.json()Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The subaccount's id, returned by POST /api/subaccount. |
fullName | string | Yes | Full legal name as it appears on the document. |
dateOfBirth | string | Yes | YYYY-MM-DD. |
countryOfTaxId | string | Yes | ISO-3 issuing country, e.g. BRA, USA or PRT. May differ from residence; some accounts require BRA for both. |
taxIdNumber | string | Yes | Tax ID issued by countryOfTaxId: CPF for BRA, national equivalent otherwise. Digits only. |
email | string | Yes | Contact email. Updates the subaccount; existing login accounts must use the email on file. |
phone | string | No | E.164 (+5511...). |
country | string | Yes | ISO-3 country of residence; some accounts require BRA. |
state | string | Yes | ISO 3166-2 subdivision without the country prefix, e.g. SP. Accounts restricted to Brazil require a valid two-letter UF. |
city | string | Yes | City of residence. |
zipCode | string | Yes | Postal code. Accounts restricted to Brazil require an 8-digit CEP; punctuation is accepted. |
streetAddress | string | Yes | Street + number + complement. |
addressNumber | string | No | Street number, e.g. 1000. Send separately for second verification; defaults to S/N when omitted. |
addressComplement | string | No | Apartment, suite or block. |
uploadedSelfieId | string | Yes | Ready SELFIE-FROM-LIVENESS document ID from POST /api/kyc/document. |
uploadedDocumentId | string | Yes | documentId of the uploaded identity document. |
Response
{
"success": true,
"data": {
"attemptId": "att_8f3a...",
"subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
"status": "PENDING",
"createdAt": "2026-05-09T22:00:00.000Z"
}
}Sending the same form again
The submission is idempotent per subaccount and documents. Sending the same form again for the same subAccountId, uploadedDocumentId and uploadedSelfieId opens nothing new: it answers 202 with the attempt the first call opened, its current status and alreadySubmitted: true. This holds after the decision too, when the document images were already deleted.
{
"success": true,
"data": {
"attemptId": "att_8f3a...",
"subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
"status": "PENDING",
"createdAt": "2026-05-09T22:00:00.000Z",
"updatedAt": "2026-05-09T22:01:43.000Z",
"rejectionReason": null,
"alreadySubmitted": true
}
}A document id already used by another submission (another subaccount, or the same document with a different selfie) is refused. Upload new documents for a new attempt.
{
"success": false,
"error": "uploadedDocumentId already used by another KYC submission",
"code": "KYC_DOCUMENT_ALREADY_USED"
}The subaccount wallet is created when the KYC is approved. Until then /api/wallet/get and /api/wallet/keys answer 404 with errorCode: "SUBACCOUNT_WALLET_NOT_PROVISIONED".
Customer already verified by Hodle
If Hodle already verified the tax ID and fullName matches (ignoring case, accents and spacing), the subaccount is linked to that identity:
{
"success": true,
"data": {
"attemptId": "link_3f9c1e2a-...",
"subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
"status": "APPROVED",
"linked": true,
"createdAt": "2026-09-30T12:00:00.000Z"
}
}Resubmitting the same subaccount returns the same attemptId and sends another KYC_APPROVED webhook with linked: true before the response. Poll the linked attemptId normally. GET /api/kyc?subAccountId=... returns linked: true and the same lastAttemptId while that identity remains verified.
Card-first verification order
Availability. Only when the card-first KYC order feature is enabled on your production account; ask support to enable it. Without it, this route behaves exactly as described above and ignores
provider.
With the feature on, an individual's verification runs through up to three steps, always in this order and one at a time:
CARD: the card verification. Offered only when card KYC is enabled on your account.DOCUMENTS: the document and liveness flow (POST /api/kyc/document, then the form payload ofPOST /api/kyc). Offered only when it is enabled on your account, and only for a subaccount.HOSTED: the hosted verification page.
A step opens only after the previous one ends with a definitive answer: rejected, or not available to the account. While a step is in progress, the next one stays closed, so the same person is never verified twice in parallel. Business subaccounts are unaffected; they keep using POST /api/kyb.
If you skip an unused step and start another provider, subsequent requests stay
with that active provider. An explicit request for an earlier unused provider
also returns 409 while verification runs. A provider outage does not prove that
a hosted verification ended, so it keeps other providers closed until the
outcome can be read.
Send the hosted payload (no form fields) to ask which step comes next:
curl --request POST \
--url https://api.hodle.com.br/api/kyc \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{ "subAccountId": "c852df87-...", "redirectUrl": "https://yourapp.com/kyc-done" }'| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | No | The subaccount to verify. Omit it to verify the account that owns the API key. |
redirectUrl | string | No | Where the hosted page sends the person when it finishes. Used by the HOSTED step only. |
provider | string | No | CARD, DOCUMENTS or HOSTED. Defaults to the active step, or the first open step when none has started. A later step can be requested to skip an earlier step that was never started. A closed step or a different provider while any verification is in progress answers 409. |
Every answer names the step in provider:
{
"success": true,
"data": {
"provider": "CARD",
"attemptId": null,
"status": "NOT_STARTED",
"url": "https://app.hodle.com.br/dashboard/card",
"expiresAt": null,
"nextStep": "POST /api/card/session"
}
}{
"success": true,
"data": {
"provider": "DOCUMENTS",
"attemptId": null,
"status": "NOT_STARTED",
"url": null,
"expiresAt": null,
"nextStep": "POST /api/kyc/document"
}
}When a documents attempt is already running, attemptId and status describe it and nextStep is null; poll GET /api/kyc/{attemptId}.
{
"success": true,
"data": {
"provider": "HOSTED",
"attemptId": "att_8f3a...",
"status": "PENDING",
"url": "https://...",
"expiresAt": null,
"nextStep": null
}
}{
"success": false,
"error": "Another KYC step is still in progress for this account",
"code": "PROVIDER_STEP_IN_PROGRESS",
"currentProvider": "DOCUMENTS"
}code | Meaning |
|---|---|
PROVIDER_STEP_IN_PROGRESS | Another provider is still running, including a later step you previously selected. Wait for it to finish. |
PROVIDER_NOT_AVAILABLE | The requested step was rejected or is not available to the account. currentProvider names the open step. |
When a step is rejected, call POST /api/kyc again without provider to receive the next step.
POST /api/kyc/import-token
Import an existing verification with a single-use share token for an applicant whose review status is GREEN. This flow requires no document uploads or liveness capture. Wait for approval through the usual poll or KYC webhook before transacting.
Ask support for the recipient forClientId before minting tokens: mint each share token for that recipient, right before calling this endpoint (tokens are short-lived and single-use). The applicant must hold a CPF in its tax id field. Only INDIVIDUAL subaccounts are supported; businesses use POST /api/kyb.
If the same identity was already approved before, the response may come back with status: APPROVED right away. Posting again for the same applicantId returns the same attemptId.
Request
curl --request POST \
--url https://api.hodle.com.br/api/kyc/import-token \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"subAccountId": "5b9f1a83b6b7c2b001f3c9e21",
"importToken": "_act-sbx-jwt-eyJhbGciOi...",
"applicantId": "65f1c2...",
"taxIdNumber": "52998224725",
"email": "maria@customer.com"
}'const res = await fetch('https://api.hodle.com.br/api/kyc/import-token', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
subAccountId: '5b9f1a83b6b7c2b001f3c9e21',
importToken: shareToken,
applicantId,
taxIdNumber: '52998224725',
email: 'maria@customer.com',
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/kyc/import-token",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
json={
"subAccountId": "5b9f1a83b6b7c2b001f3c9e21",
"importToken": share_token,
"applicantId": applicant_id,
"taxIdNumber": "52998224725",
"email": "maria@customer.com",
},
)
data = res.json()Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The subaccount to import the verification into. Must be an INDIVIDUAL subaccount you created. |
importToken | string | Yes | Single-use share token, at most 4096 characters after trimming whitespace. Never stored. |
applicantId | string | Yes | Id of the approved applicant the token was minted for. Retrying with the same id returns the same attempt. |
taxIdNumber | string | Yes | The applicant's CPF, 11 digits (punctuation is ignored). Must match the tax id on the applicant. |
email | string | Yes | The applicant's email. |
Save the returned attemptId to track the result.
Response
{
"success": true,
"data": {
"attemptId": "att_8f3a...",
"subAccountId": "5b9f1a83b6b7c2b001f3c9e21",
"source": "SUMSUB_IMPORT",
"status": "PENDING",
"createdAt": "2026-05-09T22:00:00.000Z"
}
}Treat the returned level as an opaque label; use status to determine approval.
| HTTP | errorCode | Meaning |
|---|---|---|
400 | INVALID_IMPORT_TOKEN | Missing field, or a token that was refused. Mint a new one for an approved applicant. |
409 | IMPORT_TOKEN_ALREADY_USED | The token was already consumed. Mint a new one. |
409 | TAX_ID_MISMATCH | taxIdNumber differs from the one already imported for this applicantId. |
502 | IMPORT_FAILED / IMPORT_NOT_ENABLED | Temporary failure on our side. Retry with a new token. |
GET /api/kyc/{attemptId}
Request
curl --request GET \
--url https://api.hodle.com.br/api/kyc/att_8f3a... \
--header "Authorization: Bearer $API_KEY"const res = await fetch(
`https://api.hodle.com.br/api/kyc/${attemptId}`,
{ headers: { Authorization: `Bearer ${process.env.HODLE_API_KEY}` } },
)
const data = await res.json()import os, requests
res = requests.get(
f"https://api.hodle.com.br/api/kyc/{attempt_id}",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
)
data = res.json()Response
{
"success": true,
"data": {
"attemptId": "att_8f3a...",
"subAccountId": "5b9f1a83b6b7c2b001f3c9e21",
"status": "APPROVED",
"level": 1,
"rejectionReason": null,
"rejectionLabels": [],
"createdAt": "2026-05-09T22:00:00.000Z",
"updatedAt": "2026-05-09T22:01:43.000Z"
}
}{
"success": true,
"data": {
"attemptId": "att_8f3a...",
"status": "REJECTED",
"rejectionReason": "birthdate does not match",
"rejectionLabels": ["BIRTHDATE_MISMATCH"],
"createdAt": "2026-05-09T22:00:00.000Z",
"updatedAt": "2026-05-09T22:01:43.000Z"
}
}rejectionReason is a human-readable sentence; rejectionLabels is the machine-readable
list your UI should branch on. A single attempt may contain more than one rejection label.
With second verification enabled, polls also return providers. Top-level status remains the primary result.
{
"providers": [
{ "provider": "PRIMARY", "status": "APPROVED" },
{ "provider": "SECONDARY", "status": "PROVIDER_PENDING", "updatedAt": "2026-05-09T22:03:10.000Z" }
]
}KYC rejection reasons
The following labels can be returned in rejectionLabels for a rejected KYC Level 1 attempt.
Keep the label unchanged in your integration and use the description for the user-facing
message or remediation guidance.
| Label | Meaning |
|---|---|
OBIT_INDICATION | The individual has an obituary indication on record. |
NAME_MISMATCH | The provided name does not match official records. |
BIRTHDATE_MISMATCH | The provided date of birth does not match official records. |
TAX_ID_NOT_FOUND | The provided tax identification number was not found. |
TAX_ID_IRREGULAR | The tax identification number has an irregular status. |
UNDERAGE | The individual is under the minimum required age. |
PEP | The individual is a Politically Exposed Person. |
SANCTIONS | The individual is on a current sanctions list. |
KYC_STATUS_FAILED | The identity verification could not be completed. |
CRIMINAL_LAWSUITS | Criminal lawsuits were detected for the individual. |
EXCESSIVE_LAWSUITS | An excessive number of lawsuits were detected. |
DOCUMENT_UNREADABLE | The submitted document could not be read or processed. |
DOCUMENT_NAME_MISMATCH | The name on the document does not match the provided name. |
INCONCLUSIVE | The verification was inconclusive. Contact support. |
COMPROMISED_PERSONS | Identity could not be verified due to compromised person records. |
ADVERSE_MEDIA | Adverse media findings were detected. |
CRIMINAL | Criminal records were found. |
DOCUMENT_IRREGULARITY | The submitted document has irregularities. |
SELFIE_MISMATCH | The selfie does not match the document photo. |
FRAUDULENT_LIVENESS | The liveness verification detected fraudulent behavior. |
NOT_DOCUMENT | The submitted file is not a valid identity document. |
FACE_MATCH_FAILED | The selfie does not match the face on the submitted document. |
SOURCE_FACE_CONFIDENCE_TOO_LOW | The face in the source image could not be detected with sufficient confidence. |
IMAGE_QUALITY_INSUFFICIENT | The image quality is too low for face comparison. |
FACE_POSE_NOT_SUITABLE | The face pose in the image is not suitable for verification. |
FACE_PARTIALLY_OBSTRUCTED | The face in the image is partially obstructed. |
NO_FACE_DETECTED | No face was detected in the submitted document. |
IMAGE_TOO_BLURRY | The submitted image is too blurry for verification. |
IMAGE_OVEREXPOSED | The submitted image is too bright for verification. |
IMAGE_UNDEREXPOSED | The submitted image is too dark for verification. |
DICT_MARK | The user is considered high risk by Brazilian financial institutions. |
Show the user a next step: correct data, submit a readable document or contact support. Avoid exposing sensitive screening details.
Status values
| Status | Meaning |
|---|---|
PENDING | Under review. Keep polling or wait for the webhook. |
APPROVED | Final: approved for transactions. |
REJECTED | Final: rejected. Map rejectionLabels to next steps. |
EXPIRED | Final: documents expired. Submit a new attempt. |
Second verification
Second verification is enabled per account through support. It uses the same documents and personal data after primary approval.
What changes for you when it is on:
-
The liveness page runs two captures in a row (see Liveness selfies). The user stays on the same page.
-
Running the capture on your own screen?
POST /api/kyc/documentwithSELFIE-FROM-LIVENESSalso returnssecondaryLivenessTokenandsecondaryLivenessRegion. After the first capture validates, run the second one:POST /api/public/liveness/hodle/sessionwith{ "token": secondaryLivenessToken }→{ "data": { "sessionId" } }. Call it right before the capture: a session expires minutes after it is created.POST /api/public/liveness/hodle/credentialswith the same body → temporary AWS credentials (accessKeyId,secretAccessKey,sessionToken,expiration) for theFaceLivenessDetectorcredentialProvider, withregion: secondaryLivenessRegion.- When the detector finishes,
POST /api/public/liveness/hodle/completewith the same body.
If the second capture fails or is skipped, the second verification ends as
SKIPPED. -
POST /api/kycacceptsaddressNumberandaddressComplement. Send the street number as a separate field. -
KYC webhooks carry
provider:PRIMARYon the events of the primary verification. When second-verification webhooks are also enabled for your account, the second decision arrives as anotherKYC_APPROVEDorKYC_REJECTEDfor the sameattemptIdwithprovider: "SECONDARY"(see Webhooks). -
providersappears onGET /api/kyc/{attemptId}andGET /api/kyc: aPRIMARYentry and, once the attempt is forwarded, aSECONDARYone.
Primary approval permits transactions regardless of the second result.
providers[].status (SECONDARY) | Meaning |
|---|---|
WAITING_PRIMARY | Waiting for the primary verification to decide. |
SUBMITTING | Forwarding the evidence. |
PROVIDER_PENDING | Under review by the second partner. |
APPROVED | Final: approved. |
REJECTED | Final: rejected. Read reason.code. |
REJECTED_RETRYABLE | Rejected, but a new attempt can fix it. reason.retryFrom says what to redo. |
SKIPPED | Not submitted: primary verification failed or evidence was incomplete. |
FAILED | Submission failed. Read reason.code. |
reason, when present, contains code, retryable and retryFrom:
PROVIDER_REJECTEDis final (retryable: false). Do not offer a retry.PROVIDER_EVIDENCE_REJECTEDis retryable. Collect new document photos and liveness, then submit again.
The rejection text also appears in the KYC_REJECTED webhook's reason.
KYB (business accounts)
For COMPANY subaccounts, POST /api/kyb returns hosted forms for the company and its authorized representative to complete.
Flow
POST /api/subaccountwithaccountType: "COMPANY"— returns asubAccountId.POST /api/kybwith thatsubAccountId— returns anattemptIdplus two form URLs.- Redirect the company to
basicCompanyDataUrl(company details + documents) and the signer toauthorizedRepresentativeUrl(representative's identity). - Wait for the
KYC_APPROVED/KYC_REJECTEDwebhook or pollGET /api/kyc/{attemptId}untilstatus: APPROVED.
POST /api/kyb
Request
curl --request POST \
--url https://api.hodle.com.br/api/kyb \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"subAccountId": "c852df87-ac61-4259-8242-6451658dfedb",
"redirectUrl": "https://yourapp.com/kyb-complete"
}'const res = await fetch('https://api.hodle.com.br/api/kyb', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
subAccountId,
redirectUrl: 'https://yourapp.com/kyb-complete',
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/kyb",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"subAccountId": sub_account_id,
"redirectUrl": "https://yourapp.com/kyb-complete",
},
)
data = res.json()Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | Yes | The COMPANY subaccount's id, returned by POST /api/subaccount. |
redirectUrl | string | No | Where the user is sent after the hosted forms are submitted. Must be a valid URL. |
Response
{
"success": true,
"data": {
"attemptId": "att_9b2c...",
"status": "PENDING",
"basicCompanyDataUrl": "https://kyb.hodle.com.br/company/...",
"authorizedRepresentativeUrl": "https://kyb.hodle.com.br/representative/...",
"createdAt": "2026-06-27T22:00:00.000Z"
}
}Once KYB is APPROVED, you can:
- raise the company's operating limits by submitting Proof of Address for the company and its UBO plus Proof of Financial Capacity — all three must be approved, and
- unlock USD operations by submitting Proof of Financial Capacity (e.g. a bank statement) — the same submission that counts toward the higher limits.
Third-party operations
Declare the beneficiary through taxId on POST /api/deposit/asset and POST /api/wallet/payout.
| Field | Type | Required | Description |
|---|---|---|---|
taxId | string | No | CPF of the beneficiary. Digits only. When omitted, Hodle assumes the subaccount's own taxId. |
When taxId differs from the approved account holder's, third-party operations must be enabled for the account behind your API key. Contact support to enable them. Declare the actual beneficiary, even if the PIX key or BR Code identifies someone else.
Webhook payload
When the attempt resolves, Hodle POSTs to your registered webhook one of KYC_APPROVED,
KYC_REJECTED, KYC_EXPIRED or KYC_FAILED. Register a
webhook for each event you want in the dashboard:
{
"event": "KYC_APPROVED",
"data": {
"attemptId": "att_8f3a...",
"subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
"userId": "6a70b6364c38f215e99b8c8b",
"level": "level-1",
"approvedAt": "2026-05-08T22:31:11.000Z"
}
}A subaccount linked to an existing verification gets the
same KYC_APPROVED, with linked: true, right after POST /api/kyc.
For accounts with the second verification enabled, the subaccount KYC
events carry a provider field (PRIMARY for the primary verification, SECONDARY for the
second one). See Webhooks for the exact payloads and signature verification.
Errors
| Status | When |
|---|---|
400 | Invalid JSON or fields. For KYC, check digits-only taxIdNumber, unprefixed state and ready document IDs. InvalidFieldError: uploadedSelfieId is invalid requires a new liveness capture if the document is already SELFIE-FROM-LIVENESS. A tax ID that cannot be linked returns cannot repeat taxId across multiple users. KYC submission refusals, including User has an APPROVED KYC attempt, also use this status. |
400 | Accounts restricted to Brazil require country and countryOfTaxId to be BRA, a valid UF and an 8-digit CEP (KYC_PODS_INVALID_ADDRESS). Read details for the fields to correct. |
400 | Import token missing, empty, too long, malformed, expired or refused (errorCode: INVALID_IMPORT_TOKEN). Mint a fresh token for a GREEN applicant. Other import refusals use errorCode: IMPORT_FAILED; read error before retrying. |
400 | Liveness token missing or capture validation failed. For Liveness not approved or Liveness confidence below threshold, retry capture. |
401 | Missing or invalid API key; on /api/public/liveness/credentials, invalid or expired token. |
403 | Third-party operations not enabled. On liveness session endpoints, invalid or unsupported token/capture. Register a new liveness document if retries are unavailable. |
404 | Subaccount, document, attempt or liveness session not found for your platform. |
409 | A final identity rejection prevents KYC resubmission (code: KYC_PROVIDER_REJECTED; reason carries the rejection). Do not retry it. |
409 | Import token consumed or user already imported (errorCode: IMPORT_TOKEN_ALREADY_USED): use a fresh token only if the user has not imported. Otherwise, poll the existing attempt. An import still running uses errorCode: IMPORT_IN_PROGRESS; poll it. |
502 | Import not enabled (errorCode: IMPORT_NOT_ENABLED): contact support. Liveness credentials or session unavailable: retry after a short pause. |
{
"success": false,
"error": "Validation failed",
"details": [{ "field": "taxIdNumber", "message": "must contain only digits" }]
}{
"success": false,
"error": "Validation failed",
"errorCode": "INVALID_IMPORT_TOKEN",
"details": [{ "field": "importToken", "message": "importToken is required" }]
}