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 a subAccountId. Pass accountType: "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 returned documentId in POST /api/kyc.
  • POST /api/kyc — submit an individual subaccount's personal data + document ids, get back an attemptId.
  • POST /api/kyc/import-token — reuse an existing verification through a share token and get an attemptId.
  • POST /api/kyb — start business verification for a COMPANY subaccount, get back an attemptId plus hosted form URLs.
  • GET /api/kyc/{attemptId} — poll for the result of either a KYC or a KYB attempt (PENDING → APPROVED or REJECTED).
  • 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" }'
FieldTypeRequiredDescription
namestringYesLabel to identify the subaccount. Up to 64 chars. For a business, use the legal company name.
accountTypestringNoINDIVIDUAL (default) or COMPANY. A COMPANY subaccount is verified via KYB, not KYC.
emailstringNoContact email for the subaccount.
201 Created
{ "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

  1. Collect the user's data and the ID photo in your UI.
  2. POST /api/kyc/document with documentType: "ID" (or DRIVERS-LICENSE / PASSPORT) — upload the image to the returned URL. See Uploading documents.
  3. POST /api/kyc/document with documentType: "SELFIE-FROM-LIVENESS" — send the user to the returned livenessUrl to record the selfie. See Liveness selfies.
  4. POST /api/kyc — submit the personal data referencing the two documentIds. Hodle returns an attemptId.
  5. Wait for either the KYC_APPROVED / KYC_REJECTED webhook or poll GET /api/kyc/{attemptId} every ~30 seconds.
  6. 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" }'
FieldTypeRequiredDescription
subAccountIdstringYesThe subaccount the document belongs to.
documentTypestringYesSELFIE-FROM-LIVENESS for the required liveness selfie; ID, DRIVERS-LICENSE or PASSPORT for the identity document. Plain SELFIE uploads cannot be used for KYC.
isDoubleSidedbooleanNoSet true for documents with a back side (e.g. most national IDs). Returns a second URL.
redirectUrlstringNoSELFIE-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.
201 Created — ID / DRIVERS-LICENSE / PASSPORT
{
  "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.

201 Created — SELFIE-FROM-LIVENESS
{
  "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"
  }
}
  1. Open the returned livenessUrl on 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 an iframe.
  2. Poll GET /api/kyc/document/{documentId}?subAccountId=... until ready: true.
  3. Send that documentId as uploadedSelfieId in POST /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"
200 OK
{
  "success": true,
  "data": {
    "documentId": "doc_b21...",
    "ready": true,
    "documentType": "SELFIE-FROM-LIVENESS",
    "uploadStatusFront": "COMPLETED"
  }
}
FieldDescription
readytrue when upload or capture is complete. KYC still requires the matching document type.
uploadStatusFrontWAITING-UPLOAD, PENDING, PROCESSING, COMPLETED or EXPIRED. May be omitted.
uploadErrorFrontPresent 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

FieldUse it for
sessionIdThe detector's sessionId.
livenessIdentityPoolIdThe Cognito guest identity pool that issues credentials for the session.
livenessRegionThe detector's region, and the Cognito region.
validateLivenessTokenConfirming 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..." }'
200 OK
{
  "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

FieldTypeRequiredDescription
subAccountIdstringYesThe subaccount's id, returned by POST /api/subaccount.
fullNamestringYesFull legal name as it appears on the document.
dateOfBirthstringYesYYYY-MM-DD.
countryOfTaxIdstringYesISO-3 issuing country, e.g. BRA, USA or PRT. May differ from residence; some accounts require BRA for both.
taxIdNumberstringYesTax ID issued by countryOfTaxId: CPF for BRA, national equivalent otherwise. Digits only.
emailstringYesContact email. Updates the subaccount; existing login accounts must use the email on file.
phonestringNoE.164 (+5511...).
countrystringYesISO-3 country of residence; some accounts require BRA.
statestringYesISO 3166-2 subdivision without the country prefix, e.g. SP. Accounts restricted to Brazil require a valid two-letter UF.
citystringYesCity of residence.
zipCodestringYesPostal code. Accounts restricted to Brazil require an 8-digit CEP; punctuation is accepted.
streetAddressstringYesStreet + number + complement.
addressNumberstringNoStreet number, e.g. 1000. Send separately for second verification; defaults to S/N when omitted.
addressComplementstringNoApartment, suite or block.
uploadedSelfieIdstringYesReady SELFIE-FROM-LIVENESS document ID from POST /api/kyc/document.
uploadedDocumentIdstringYesdocumentId of the uploaded identity document.

Response

202 Accepted
{
  "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.

202 Accepted — already submitted
{
  "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.

409 Conflict — document already used
{
  "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:

200 OK — linked to an existing verification
{
  "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:

  1. CARD: the card verification. Offered only when card KYC is enabled on your account.
  2. DOCUMENTS: the document and liveness flow (POST /api/kyc/document, then the form payload of POST /api/kyc). Offered only when it is enabled on your account, and only for a subaccount.
  3. 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" }'
FieldTypeRequiredDescription
subAccountIdstringNoThe subaccount to verify. Omit it to verify the account that owns the API key.
redirectUrlstringNoWhere the hosted page sends the person when it finishes. Used by the HOSTED step only.
providerstringNoCARD, 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:

200 OK — card step
{
  "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"
  }
}
200 OK — documents step
{
  "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}.

201 Created — hosted step
{
  "success": true,
  "data": {
    "provider": "HOSTED",
    "attemptId": "att_8f3a...",
    "status": "PENDING",
    "url": "https://...",
    "expiresAt": null,
    "nextStep": null
  }
}
409 Conflict — step not open
{
  "success": false,
  "error": "Another KYC step is still in progress for this account",
  "code": "PROVIDER_STEP_IN_PROGRESS",
  "currentProvider": "DOCUMENTS"
}
codeMeaning
PROVIDER_STEP_IN_PROGRESSAnother provider is still running, including a later step you previously selected. Wait for it to finish.
PROVIDER_NOT_AVAILABLEThe 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

FieldTypeRequiredDescription
subAccountIdstringYesThe subaccount to import the verification into. Must be an INDIVIDUAL subaccount you created.
importTokenstringYesSingle-use share token, at most 4096 characters after trimming whitespace. Never stored.
applicantIdstringYesId of the approved applicant the token was minted for. Retrying with the same id returns the same attempt.
taxIdNumberstringYesThe applicant's CPF, 11 digits (punctuation is ignored). Must match the tax id on the applicant.
emailstringYesThe applicant's email.

Save the returned attemptId to track the result.

Response

202 Accepted
{
  "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.

HTTPerrorCodeMeaning
400INVALID_IMPORT_TOKENMissing field, or a token that was refused. Mint a new one for an approved applicant.
409IMPORT_TOKEN_ALREADY_USEDThe token was already consumed. Mint a new one.
409TAX_ID_MISMATCHtaxIdNumber differs from the one already imported for this applicantId.
502IMPORT_FAILED / IMPORT_NOT_ENABLEDTemporary 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

status: APPROVED
{
  "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"
  }
}
status: REJECTED
{
  "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
{
  "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.

LabelMeaning
OBIT_INDICATIONThe individual has an obituary indication on record.
NAME_MISMATCHThe provided name does not match official records.
BIRTHDATE_MISMATCHThe provided date of birth does not match official records.
TAX_ID_NOT_FOUNDThe provided tax identification number was not found.
TAX_ID_IRREGULARThe tax identification number has an irregular status.
UNDERAGEThe individual is under the minimum required age.
PEPThe individual is a Politically Exposed Person.
SANCTIONSThe individual is on a current sanctions list.
KYC_STATUS_FAILEDThe identity verification could not be completed.
CRIMINAL_LAWSUITSCriminal lawsuits were detected for the individual.
EXCESSIVE_LAWSUITSAn excessive number of lawsuits were detected.
DOCUMENT_UNREADABLEThe submitted document could not be read or processed.
DOCUMENT_NAME_MISMATCHThe name on the document does not match the provided name.
INCONCLUSIVEThe verification was inconclusive. Contact support.
COMPROMISED_PERSONSIdentity could not be verified due to compromised person records.
ADVERSE_MEDIAAdverse media findings were detected.
CRIMINALCriminal records were found.
DOCUMENT_IRREGULARITYThe submitted document has irregularities.
SELFIE_MISMATCHThe selfie does not match the document photo.
FRAUDULENT_LIVENESSThe liveness verification detected fraudulent behavior.
NOT_DOCUMENTThe submitted file is not a valid identity document.
FACE_MATCH_FAILEDThe selfie does not match the face on the submitted document.
SOURCE_FACE_CONFIDENCE_TOO_LOWThe face in the source image could not be detected with sufficient confidence.
IMAGE_QUALITY_INSUFFICIENTThe image quality is too low for face comparison.
FACE_POSE_NOT_SUITABLEThe face pose in the image is not suitable for verification.
FACE_PARTIALLY_OBSTRUCTEDThe face in the image is partially obstructed.
NO_FACE_DETECTEDNo face was detected in the submitted document.
IMAGE_TOO_BLURRYThe submitted image is too blurry for verification.
IMAGE_OVEREXPOSEDThe submitted image is too bright for verification.
IMAGE_UNDEREXPOSEDThe submitted image is too dark for verification.
DICT_MARKThe 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

StatusMeaning
PENDINGUnder review. Keep polling or wait for the webhook.
APPROVEDFinal: approved for transactions.
REJECTEDFinal: rejected. Map rejectionLabels to next steps.
EXPIREDFinal: 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/document with SELFIE-FROM-LIVENESS also returns secondaryLivenessToken and secondaryLivenessRegion. After the first capture validates, run the second one:

    1. POST /api/public/liveness/hodle/session with { "token": secondaryLivenessToken } → { "data": { "sessionId" } }. Call it right before the capture: a session expires minutes after it is created.
    2. POST /api/public/liveness/hodle/credentials with the same body → temporary AWS credentials (accessKeyId, secretAccessKey, sessionToken, expiration) for the FaceLivenessDetector credentialProvider, with region: secondaryLivenessRegion.
    3. When the detector finishes, POST /api/public/liveness/hodle/complete with the same body.

    If the second capture fails or is skipped, the second verification ends as SKIPPED.

  • POST /api/kyc accepts addressNumber and addressComplement. Send the street number as a separate field.

  • KYC webhooks carry provider: PRIMARY on the events of the primary verification. When second-verification webhooks are also enabled for your account, the second decision arrives as another KYC_APPROVED or KYC_REJECTED for the same attemptId with provider: "SECONDARY" (see Webhooks).

  • providers appears on GET /api/kyc/{attemptId} and GET /api/kyc: a PRIMARY entry and, once the attempt is forwarded, a SECONDARY one.

Primary approval permits transactions regardless of the second result.

providers[].status (SECONDARY)Meaning
WAITING_PRIMARYWaiting for the primary verification to decide.
SUBMITTINGForwarding the evidence.
PROVIDER_PENDINGUnder review by the second partner.
APPROVEDFinal: approved.
REJECTEDFinal: rejected. Read reason.code.
REJECTED_RETRYABLERejected, but a new attempt can fix it. reason.retryFrom says what to redo.
SKIPPEDNot submitted: primary verification failed or evidence was incomplete.
FAILEDSubmission failed. Read reason.code.

reason, when present, contains code, retryable and retryFrom:

  • PROVIDER_REJECTED is final (retryable: false). Do not offer a retry.
  • PROVIDER_EVIDENCE_REJECTED is 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

  1. POST /api/subaccount with accountType: "COMPANY" — returns a subAccountId.
  2. POST /api/kyb with that subAccountId — returns an attemptId plus two form URLs.
  3. Redirect the company to basicCompanyDataUrl (company details + documents) and the signer to authorizedRepresentativeUrl (representative's identity).
  4. Wait for the KYC_APPROVED / KYC_REJECTED webhook or poll GET /api/kyc/{attemptId} until status: 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

FieldTypeRequiredDescription
subAccountIdstringYesThe COMPANY subaccount's id, returned by POST /api/subaccount.
redirectUrlstringNoWhere the user is sent after the hosted forms are submitted. Must be a valid URL.

Response

202 Accepted
{
  "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.

FieldTypeRequiredDescription
taxIdstringNoCPF 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

StatusWhen
400Invalid 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.
400Accounts 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.
400Import 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.
400Liveness token missing or capture validation failed. For Liveness not approved or Liveness confidence below threshold, retry capture.
401Missing or invalid API key; on /api/public/liveness/credentials, invalid or expired token.
403Third-party operations not enabled. On liveness session endpoints, invalid or unsupported token/capture. Register a new liveness document if retries are unavailable.
404Subaccount, document, attempt or liveness session not found for your platform.
409A final identity rejection prevents KYC resubmission (code: KYC_PROVIDER_REJECTED; reason carries the rejection). Do not retry it.
409Import 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.
502Import not enabled (errorCode: IMPORT_NOT_ENABLED): contact support. Liveness credentials or session unavailable: retry after a short pause.
400 — validation
{
  "success": false,
  "error": "Validation failed",
  "details": [{ "field": "taxIdNumber", "message": "must contain only digits" }]
}
400 — no token sent
{
  "success": false,
  "error": "Validation failed",
  "errorCode": "INVALID_IMPORT_TOKEN",
  "details": [{ "field": "importToken", "message": "importToken is required" }]
}