Bureau Runs API: Trigger and Retrieve KYC Results

The bureau runs API lets you programmatically trigger KYC verification for any CPF or CNPJ, poll for results, and retrieve the full compliance decision — including per-source findings, triggered decision rules, and the AI-built risk analysis. Every run is scoped to your tenant and tied to a published KYC template that defines which data sources to query and how to interpret the results.

POST /api/v1/bureau/runs

Creates and immediately triggers a new bureau run for the subject document you specify. The run executes asynchronously against all sources configured in the template. You always receive a 202 Accepted response with a run_id you can use to poll for completion. Authentication: X-API-Key with runs:write scope. You may also pass the key as Authorization: Bearer <key>.

Request body

template_id

string

required

The ID of the published KYC template to execute. The template must belong to your account or be a global template. You can find template IDs in the kycert dashboard under Templates.

parametros

object

required

An object containing the subject’s data. The required fields depend on the template’s parametros_schema. At minimum, you must include the document field (typically cpf for PF templates or cnpj for PJ templates).

Show Common parametros fields

parametros.cpf

string

CPF of the subject for PF templates (e.g., "123.456.789-09"). Masks are stripped automatically.

parametros.cnpj

string

CNPJ of the subject for PJ templates (e.g., "12.345.678/0001-90"). Masks are stripped automatically.

parametros.name

string

Full name or company name of the subject. Used to enrich source queries and display in reports.

parametros.data_nascimento

string

Date of birth for PF subjects, in YYYY-MM-DD format. Required by some sources for identity validation.

parametros.webhook_url

string

A per-run webhook URL override. When set, kycert delivers the run completion event to this URL instead of your account’s default webhook endpoint.

external_id

string

Your system’s reference ID for this run. Stored in flags.external_id and returned on every response. Use this to correlate runs with your internal records without additional lookups. You can also filter the list endpoint by external_id.

metadata

object

Custom key-value pairs attached to the run. Keys and values must both be strings. Maximum 10 keys; each value must not exceed 500 characters. Metadata is returned on GET /runs, GET /runs/{id}, and GET /runs/{id}/analysis responses.

{
  "metadata": {
    "broker_account_id": "acc_87231",
    "onboarding_flow": "fx_spot"
  }
}

Idempotency

Pass an Idempotency-Key: <your-unique-key> request header to make POST /api/v1/bureau/runs idempotent. If kycert receives a second request with the same key within 24 hours for the same tenant, it returns the original run_id and status without triggering a new run. Use a UUID or a hash of your external_id.

Response — 202 Accepted

The run is always enqueued asynchronously. You receive 202 immediately.

{
  "run_id": "run_01j9a4x2fz0k8p3vy7n5cw6m1d",
  "status": "queued",
  "estimated_seconds": 35,
  "livemode": true
}

run_id

string

Unique identifier for the run. Use this to poll GET /api/v1/bureau/runs/{id} for completion.

status

string

Always "queued" on creation.

estimated_seconds

number

Estimated seconds until the run completes, calculated from the slowest enabled source in the template. Treat this as a hint for your polling interval — actual duration may vary.

livemode

boolean

true when the run executes against live data sources. false in the sandbox environment, where results are simulated.

curl example

curl -X POST https://api.kycert.com.br/api/v1/bureau/runs \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "template_id": "tpl_01j8z3kqwp9r2n4hm6x7yc0fb5",
    "parametros": {
      "cpf": "123.456.789-09",
      "name": "João da Silva",
      "data_nascimento": "1985-04-22"
    },
    "external_id": "cliente_4821",
    "metadata": {
      "broker_account_id": "acc_87231",
      "onboarding_flow": "fx_spot"
    }
  }'

Error responses

HTTP status	`error.code`	Cause
`400`	`missing_template_id`	`template_id` was omitted or not a string.
`400`	`template_not_found`	Template does not exist or is not active for your account.
`400`	`invalid_parametros`	One or more required `parametros` fields are missing or unknown. The response includes an `invalid_params` array.
`400`	`missing_document`	The document field (e.g., `cpf` or `cnpj`) was not found in `parametros`.
`400`	`invalid_document`	The document does not have 11 digits (CPF) or 14 digits (CNPJ).
`402`	`billing_suspended`	Your account is suspended or has insufficient credit.
`403`	`insufficient_scope`	The API key does not have `runs:write` scope.
`429`	`rate_limit_exceeded`	The API key has exceeded its usage limit.

GET /api/v1/bureau/runs

Lists all bureau runs for your account in reverse chronological order. Results are paginated using a cursor. Authentication: X-API-Key with runs:read scope.

Query parameters

cursor

string

Opaque pagination cursor returned as next_cursor in the previous response. Pass this value to retrieve the next page.

limit

number

Number of runs to return per page. Minimum 1, maximum 100, default 20.

status

string

Filter by run status. Accepted values: pending, running, em_analise, completed, failed, partial, cancelado.

template_id

string

Filter runs to those executed against a specific template.

external_id

string

Filter runs by your reference ID, set via external_id at creation time.

created_after

string

ISO 8601 timestamp. Returns only runs created at or after this time (e.g., 2024-01-15T00:00:00Z).

created_before

string

ISO 8601 timestamp. Returns only runs created before or at this time.

Response — 200 OK

{
  "data": [
    {
      "run_id": "run_01j9a4x2fz0k8p3vy7n5cw6m1d",
      "template_id": "tpl_01j8z3kqwp9r2n4hm6x7yc0fb5",
      "status": "completed",
      "decision": "approved",
      "risk_band": "baixo",
      "subject_type": "pf",
      "external_id": "cliente_4821",
      "metadata": {
        "broker_account_id": "acc_87231"
      },
      "created_at": "2024-08-14T13:42:00.000Z",
      "completed_at": "2024-08-14T13:42:38.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wOC0xNCJ9",
  "livemode": true
}

data

Run[]

Array of run summary objects.

Show Run object fields

run_id

string

Unique run identifier.

template_id

string

ID of the template used.

status

string

Current run status.

decision

string

Final compliance decision: approved, rejected, or review. null if the run has not completed.

risk_band

string

Risk band assigned by the analysis engine: baixo, medio, or alto. null if not yet computed.

subject_type

string

"pf" for individual or "pj" for company.

external_id

string | null

Your reference ID, if provided at creation.

metadata

object | null

Custom key-value metadata attached at creation.

created_at

string

ISO 8601 timestamp of run creation.

completed_at

string | null

ISO 8601 timestamp of run completion. null if still running.

has_more

boolean

true if additional pages exist. Pass next_cursor to retrieve the next page.

next_cursor

string

Opaque cursor for the next page. Only present when has_more is true.

livemode

boolean

true when the results come from live runs.

curl example

curl "https://api.kycert.com.br/api/v1/bureau/runs?status=completed&limit=10" \
  -H "X-API-Key: sk_live_your_key_here"

GET /api/v1/bureau/runs/{id}

Retrieves a single bureau run by its run_id. While the run is still executing, this endpoint returns 202 with status: "running" and a retry_after_seconds hint. Once completed, it returns 200 with the full result. Authentication: X-API-Key with runs:read scope.

Path parameters

string

required

The run_id returned when the run was created.

Response — 202 (run still executing)

{
  "run_id": "run_01j9a4x2fz0k8p3vy7n5cw6m1d",
  "status": "running",
  "retry_after_seconds": 8,
  "livemode": true
}

Response — 200 (run completed)

{
  "run_id": "run_01j9a4x2fz0k8p3vy7n5cw6m1d",
  "status": "completed",
  "decision": "approved",
  "operative_decision": "approved",
  "risk_band": "baixo",
  "external_id": "cliente_4821",
  "metadata": {
    "broker_account_id": "acc_87231"
  },
  "created_at": "2024-08-14T13:42:00.000Z",
  "completed_at": "2024-08-14T13:42:38.000Z",
  "livemode": true
}

run_id

string

Unique run identifier.

status

string

Final run status. One of: completed, failed, partial, cancelado. For in-progress runs, see the 202 response above.

decision

string

Overall compliance decision computed from the decision rules in the template: approved, rejected, or review.

operative_decision

string

The operative decision after accounting for incomplete critical sources. Returns hold when one or more tier-1 sources failed to return data, regardless of the overall decision.

risk_band

string

Aggregate risk band assigned to the subject: baixo, medio, or alto.

external_id

string | null

Your reference ID, echoed back from creation.

metadata

object | null

Custom key-value metadata set at creation time.

created_at

string

ISO 8601 timestamp.

completed_at

string | null

ISO 8601 timestamp of completion. null when the run is still in progress.

livemode

boolean

Environment indicator.

curl example

curl "https://api.kycert.com.br/api/v1/bureau/runs/run_01j9a4x2fz0k8p3vy7n5cw6m1d" \
  -H "X-API-Key: sk_live_your_key_here"

GET /api/v1/bureau/runs/{id}/analysis

Returns the full risk analysis for a completed run. The analysis is computed deterministically from the source results — it includes the structured risk dimensions, per-finding detail, and a subject profile extracted from identity sources. If the run is still executing, this endpoint returns 202. Authentication: X-API-Key with runs:read scope.

Path parameters

string

required

The run_id of a completed run.

Response — 200 OK

{
  "meta": {
    "schema_version": "v1",
    "generated_at": "2024-08-14T13:42:39.000Z",
    "run_id": "run_01j9a4x2fz0k8p3vy7n5cw6m1d",
    "external_id": "cliente_4821"
  },
  "metadata": {
    "broker_account_id": "acc_87231"
  },
  "analysis": {
    "schema_version": "v1",
    "built_at": "2024-08-14T13:42:39.000Z",
    "decision": "approved",
    "operative_decision": "approved",
    "confidence": "full",
    "blocked_by": [],
    "review_reasons": [],
    "incomplete_sources": [],
    "risk_dimensions": [
      {
        "id": "identidade",
        "label": "Identidade",
        "band": "baixo",
        "score": 10,
        "detail": "Situação cadastral regular. Nenhuma restrição encontrada."
      }
    ],
    "findings": [
      {
        "check_id": "is_pep",
        "source_id": "bdc_basic_data_pf",
        "source_label": "Dados Cadastrais",
        "severity": "low",
        "title": "Não é Pessoa Politicamente Exposta",
        "detail": null
      }
    ],
    "source_groups": []
  },
  "livemode": true
}

curl example

curl "https://api.kycert.com.br/api/v1/bureau/runs/run_01j9a4x2fz0k8p3vy7n5cw6m1d/analysis" \
  -H "X-API-Key: sk_live_your_key_here"

GET /api/v1/bureau/runs/{id}/report

Downloads the PDF compliance report for a completed bureau run. The report is generated on demand and stored immutably — subsequent calls for the same run_id and mode return the identical document. Authentication: X-API-Key with runs:read scope.

Report generation is triggered separately from the run. Use POST /api/v1/bureau/runs/{id}/report (dashboard-only) to generate the PDF before downloading. Once generated, GET returns it immediately via a 302 redirect to a time-limited signed URL.

Path parameters

string

required

The run_id of a completed run.

Query parameters

mode

string

required

Report format. Either "resumido" (summary, ~3 pages) or "completo" (full dossier, 20+ pages).

resumido — overall decision, risk band, key findings, and analyst sign-off block.
completo — all source data, partner graphs, legal processes, complete check details, and appendix.

Response — 302 Redirect → `application/pdf`

The endpoint redirects to a signed download URL valid for 1 hour. Your HTTP client follows the redirect and streams the binary PDF.

Requesting mode=completo may take a few seconds longer on the first call, as the full dossier renders all source data, QSA partner runs, and appendix pages. Subsequent requests for the same run return the cached PDF instantly.

curl example

# Download the summary report
curl -L "https://api.kycert.com.br/api/v1/bureau/runs/run_01j9a4x2fz0k8p3vy7n5cw6m1d/report?mode=resumido" \
  -H "X-API-Key: sk_live_your_key_here" \
  --output report-resumido.pdf

# Download the full dossier
curl -L "https://api.kycert.com.br/api/v1/bureau/runs/run_01j9a4x2fz0k8p3vy7n5cw6m1d/report?mode=completo" \
  -H "X-API-Key: sk_live_your_key_here" \
  --output report-completo.pdf

Error responses

HTTP status	Cause
`400`	Missing or invalid `mode` parameter.
`400`	Run has not reached a terminal status yet.
`404`	Report has not been generated yet. Use the dashboard or the POST endpoint to generate it first.

​POST /api/v1/bureau/runs

​Request body

​Idempotency

​Response — 202 Accepted

​curl example

​Error responses

​GET /api/v1/bureau/runs

​Query parameters

​Response — 200 OK

​curl example

​GET /api/v1/bureau/runs/{id}

​Path parameters

​Response — 202 (run still executing)

​Response — 200 (run completed)

​curl example

​GET /api/v1/bureau/runs/{id}/analysis

​Path parameters

​Response — 200 OK

​curl example

​GET /api/v1/bureau/runs/{id}/report

​Path parameters

​Query parameters

​Response — 302 Redirect → application/pdf

​curl example

​Error responses

POST /api/v1/bureau/runs

Request body

Idempotency

Response — 202 Accepted

curl example

Error responses

GET /api/v1/bureau/runs

Query parameters

Response — 200 OK

curl example

GET /api/v1/bureau/runs/{id}

Path parameters

Response — 202 (run still executing)

Response — 200 (run completed)

curl example

GET /api/v1/bureau/runs/{id}/analysis

Path parameters

Response — 200 OK

curl example

GET /api/v1/bureau/runs/{id}/report

Path parameters

Query parameters

Response — 302 Redirect → `application/pdf`

curl example

Error responses