KYC

All endpoints require Authorization: Bearer <token> and the x-client-id: <Client_ID> header — your tenant id is the same value as your OAuth Client_ID (details); without it requests fail with 400 MISSING_CLIENT_ID. The KYC product must be enabled for your tenant — otherwise calls return 403 PRODUCT_NOT_ENABLED.

Overview

The KYC API lets your tenant request identity verification processes (background-check and, optionally, document verification) for natural persons (PF) and legal entities (PJ), entirely via API. Each consultation is billed per successful call, according to the type (PF/PJ) and the model chosen.

Background-check models

The backgroundcheckModel field defines the depth of the verification (and the amount of data returned):

Model	Description
BASIC	Essential identity validation
MEDIUM	Extended validation
COMPLETE	Full background check

The unit price varies by type (PF/PJ) and model, per your contract.

Asynchronous flow

KYC is asynchronous:

1. You start the process (POST /v1/kyc/person or /v1/kyc/company). The response returns a kycUUID and status: "PROCESSING".
2. The result is processed asynchronously (kyc-backgroundcheck and kyc-documentscopy processes) — track it by polling GET /v1/kyc/list (webhook push for kyc-* events is on the roadmap).
3. When documentscopyFlag = true, a webview URL is generated (delivered asynchronously) that the end user must complete to finish the document verification.

Billing occurs on successful initiation (when the kycUUID is returned), idempotent by kycUUID.

---

POST /v1/kyc/person

Starts a KYC process for a natural person (identified by CPF).

Body:

Field	Type	Required	Description
backgroundcheckModel	string	Yes	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Yes	If true, starts document verification (generates a webview) after the background-check
vatNumber	string	Yes	CPF (11 digits)
name	string	Yes	Full name
birthDate	string	Yes	Date of birth (dd-mm-yyyy)
motherName	string	Yes	Full mother's name

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PF",
    "model": "BASIC",
    "documentscopy": true,
    "webviewUrl": null
  }
}

webviewUrl may be null at initiation and filled in later — poll GET /v1/kyc/list until it appears.

---

POST /v1/kyc/company

Starts a KYC process for a legal entity (identified by CNPJ).

Body:

Field	Type	Required	Description
backgroundcheckModel	string	Yes	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Yes	If true, generates a document-verification webview for each qsa member
vatNumber	string	Yes	CNPJ (14 digits)
legalName	string	Yes	Legal name (razão social)
qsa	array	Yes	Owners & administrators (1 to 3 records); at least one SOCIO_ADMINISTRADOR

Each qsa item:

Field	Type	Description
ownerType	string	SOCIO_ADMINISTRADOR | SOCIO
vatNumber	string	Owner's CPF
name	string	Owner's name
birthDate	string	Date of birth (dd-mm-yyyy)
motherName	string	Owner's mother's name

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PJ",
    "model": "COMPLETE",
    "documentscopy": false
  }
}

---

GET /v1/kyc/list

Lists your tenant's KYC processes (with the latest status). The list is served from our internal registry, scoped to your tenant — you never see other tenants' processes.

Query params:

Param	Type	Required	Description
kycUUID	string	No	Filter by a specific process

Response 200 OK:

{
  "data": {
    "result": [
      {
        "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
        "vatNumber": "111***11",
        "process": "kyc-backgroundcheck",
        "status": "APPROVED",
        "kycType": "PF"
      }
    ]
  }
}

• process: kyc-backgroundcheck | kyc-documentscopy
• status: APPROVED | REPROVED | PROCESSING | PENDING
• vatNumber is returned masked.

---

POST /v1/kyc/manual-decision

Applies a manual decision (approve/reject) to one of your tenant's KYC processes. The kycUUID must belong to your tenant.

Body:

Field	Type	Required	Description
kycUUID	string	Yes	Process identifier
decision	string	Yes	APPROVED | REPROVED
reason	string	Yes	Justification (up to 500 chars)

Response 200 OK:

{
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "decision": "APPROVED"
  }
}

---

Status Tracking

KYC processes are updated asynchronously:

Process	Fires when
kyc-backgroundcheck	Background-check completion/update
kyc-documentscopy	Webview generation and document-verification completion/update

Each record carries the kycUUID and the status (APPROVED | REPROVED | PROCESSING | PENDING).

Poll for status. Today tracking is done via GET /v1/kyc/list (e.g. every 30s while PROCESSING). kyc-* events are not yet delivered to the tenant webhook — webhook push (minimal payload kycUUID + status) is on the roadmap. Account onboarding webhooks (onboarding-*, including onboarding-biometrics) are unaffected and delivered normally.

---

Common errors

HTTP	Situation
400	Invalid backgroundcheckModel, missing CPF/CNPJ, qsa without a SOCIO_ADMINISTRADOR
403	KYC product not enabled for the tenant; or a kycUUID from another tenant in manual-decision

See Error Handling for the standard error envelope.