CPF dossier

Creates a compliance dossier for an individual: PEP, sanctions (CEIS and CNEP), federal administration expulsions (CEAF), TCU lists, slave labor, federal active debt (PGFN) and international sanctions. Processing is asynchronous: the API replies 202 with a dossie_id, and you read the result with GET /v1/dossie/cpf/{id} or get a notice at your callback_url.

Request body

cpfstringrequired

CPF with or without punctuation.

descriptionstringrequired

Purpose of the lookup, 1 to 200 characters. Example: "Anti-money laundering".

birthdatestringrequired

Birth date of the individual, YYYY-MM-DD. The cadastral lookup is the same as POST /v1/cpf and checks CPF and birth date together; on a mismatch the dossier ends as failed (CPF_NOT_FOUND). It is neither returned nor stored.

callback_urlstring

Public HTTPS URL that receives a notice when the dossier finishes. No IP address, localhost or port other than 443.

100 credits per completed dossier. Failed dossiers are not charged.

• The birth date is required, as in POST /v1/cpf; missing or invalid returns 400. basic_info (name, cadastral status and birth date) comes from the BrazID base and, if the CPF is not in it yet, is fetched with the standard cadastral lookup at no extra cost. If the CPF does not exist or the birth date does not match, the dossier ends as failed with the code CPF_NOT_FOUND and nothing is charged.
• Privacy (LGPD): the full CPF, name and birth date are kept for 30 days. After that they are erased and the history keeps the masked CPF, the purpose, the risk and the findings. At the data subject's request the erasure is immediate.
• Without a balance for 100 credits (and no overage), the response is 402 and the dossier does not start. A malformed CPF returns 400 and an invalid check digit returns 422.
• If a source is unavailable, the dossier ends with status failed and nothing is charged. Just submit it again.
• Available in the sandbox. In production the endpoint is not released yet and returns 503 with the code DOSSIER_UNAVAILABLE.

How a dossier is processed

1. 1

   You send the CPF, the birth date and the purpose

   The API validates the input, checks the balance and replies 202 with the dossie_id and the status pending. Nothing is charged at this step.

2. 2

   Sources are queried in parallel

   CGU (PEP, CEIS, CNEP and CEAF), TCU (unfit bidders, disqualified, irregular accounts and electoral), the slave labor registry, active debt (PGFN) and international sanctions are queried at the same time, in the background. Checks that only need the CPF start together with the registry lookup.

3. 3

   You follow along

   Call GET /v1/dossie/cpf/{id} until the status is completed or failed, or wait for the notice at your callback_url.

4. 4

   Charged once

   The 100 credits are debited only when every source answers. The history is kept in your account and can be read at any time, at no extra cost; personal data is erased after 30 days.

202 response fields

successboolean

Always true when the dossier was accepted.

data.dossie_idstring

Dossier identifier. Use it to follow progress.

data.statusstring

pending on creation. Then completed or failed.

data.created_atstring

Creation date and time, ISO 8601 (UTC).

data.queryobject

What was queried: cpf (digits only) and description.

data.status_urlstring

Path to follow the dossier. Also sent in the Location header.

credits_remainingnumber

Current balance. It does not include the 100 credits of this dossier yet. Can be hidden in the dashboard.

Test CPFs in the sandbox

In the sandbox (api-sandbox.brazid.com) the dossier uses these CPFs, with no credits charged. Any other CPF ends as failed with CPF_NOT_FOUND.

Notice at callback_url

• When the dossier finishes, we send a POST with the event dossie.completed or dossie.failed, the dossie_id, the status and, if completed, the risk_level.
• The notice carries no personal data. To read the result, call GET /v1/dossie/cpf/{id}.
• If you have a webhook set up in the dashboard, the body is signed in the x-brazid-signature header, like the other webhooks. Without a webhook, the notice is sent unsigned.
• Up to 3 attempts in a row if your server fails (5xx, 408, 429 or no response). Do not rely on the notice alone: the GET stays available.