How a bureau run works
Customer registers or you trigger a manual lookup
A bureau run starts when a customer completes onboarding on your white-label portal, when you initiate a lookup from Bureau → Lookup, or when your system calls the API. The subject’s CPF or CNPJ is the entry point.
kycert reads your active KYC template
The engine loads a point-in-time snapshot of the template assigned to this run. The snapshot records exactly which sources are active, in which phase, and with which
on_hit rules — so the run is always reproducible even if you later change the template.Critical-phase sources run sequentially
Sources in the critical phase execute one at a time. If any source returns INVALID and its rule is set to
block, the run stops immediately and the customer is rejected. No further credits are consumed.Important and additional phases run in parallel
Once the critical phase passes, sources in the important and additional phases execute concurrently. This keeps the total run time short even when many sources are active.
The decision engine aggregates all results into a risk band
After all sources complete, the engine calculates an overall risk band — high, medium, or low — based on the combination of INVALID, NO_DATA, and VALID results across phases and their configured weights.
The result is stored in an immutable compliance record
The complete run — every source result, the template snapshot, the risk band, and the final decision — is written to an append-only audit log. You cannot edit or delete it. This record satisfies the documentation obligation under BCB Circular 3.978/2020.
The 4-status model
Every source in a bureau run returns exactly one of four statuses. Your template rules then determine what happens next.| Status | Meaning | Default action |
|---|---|---|
| VALID | Source found no compliance issues for this subject | Continue to next source or phase |
| INVALID | Source detected a compliance issue (e.g., active arrest warrant, sanctions match) | Block or flag for manual review, depending on the on_hit rule configured in your template |
| NO_DATA | Source returned no record for the document — subject not found in that database | Informational only — never triggers a block |
| ERROR | Technical failure communicating with the source | Automatically retried once with backoff; if it fails again, the result is recorded as ERROR |
Execution phases
Phases give you precise control over sequencing and consequence. Assign each source to the phase that matches its compliance weight.| Phase | Execution mode | INVALID consequence | Typical sources |
|---|---|---|---|
| Critical | Sequential — stops on first block | Customer rejected immediately (if on_hit: block) | cnj_mandados_prisao, receita_federal_cpf, uk_sanctions, eu_sanctions |
| Important | Parallel — all sources run | Customer placed in manual review queue (if on_hit: pending) | pep_coaf, cgu_cnc, sit_trabalho_escravo |
| Additional | Parallel — all sources run | Never blocks or flags — enriches the profile only | tse_doadores_2024, icij_offshore_leaks, bdc_financial_data_pf |
Reliability features
kycert builds fault tolerance directly into the engine so that a single failing external source never blocks your entire onboarding queue. Circuit breaker — the engine tracks consecutive failures for each source. After five failures, the circuit opens and that source is automatically bypassed for two minutes before the engine retries in half-open mode. Other sources continue running unaffected. You can see circuit-open events in the run detail console. Cross-tenant cache — results are cached by source and document hash. If the same CPF was queried by another brokerage in the last cache window, kycert returns the cached result rather than making a duplicate call to the data provider. This reduces your credit consumption on high-volume tenants. Auto-retry — when a source returns ERROR, the engine waits briefly and retries the call once. If the second attempt succeeds, the run continues normally. If it fails again, the result is marked ERROR and the run proceeds based on your template’s fallback rules.Credits
Each source execution consumes credits from your plan balance. Credits for critical-phase sources are debited atomically at the point the source runs — if the run short-circuits before reaching the important phase, only the critical-phase credits consumed up to that point are deducted. Sources that return ERROR on both attempts may be eligible for credit reimbursement per your plan terms. Contact your account manager to review your credit statement or query consumption history in Configurações → Faturas.Credit pricing per source is shown in the source catalog inside the template builder. You can estimate the cost of a template before publishing it.
Next steps
Templates
Configure which sources run and what happens on each result.
Runs
View run history, download PDF reports, and inspect source-level findings.
Data Sources
Browse all 28+ integrated sources with descriptions and coverage details.