Verifications
A Verification is the core resource of the Buró de Ingresos API. It represents a single async request to retrieve income and identity data for an identifier, whether that identifier is a CURP (individual) or a 12-char RFC (business).
This page covers the verification lifecycle, the Verification object, and how to react to its completion.
Lifecycle
A verification moves through this flow:
- Create. Call
POST /verificationswith anidentifierand theip_addressfrom which the data owner accepted your privacy notice. For individuals (18-char CURP),phoneis required too. The API records consent with the verification under your company's registered privacy notice. This consent applies only to that verification, so includeip_addressin every verification request. - In progress. The verification is queued and processed asynchronously. The initial response returns
status: "in_progress"and theconsent_idused. - Completed. When processing finishes, BDI sends a
verification.completedwebhook to your registered endpoint. The webhook payload reflects the final state, including which data entities are available. - Fetch data. Once completed and
data_availableistrue, retrieve the relevant data from the resource endpoints listed inentities.
Verifications are append-only from your side: you do not poll for status or modify a verification mid-flight. Always wait for the webhook and use the entities array to know which endpoints have data.
For the create payload, the contact field (phone), the optional rfc, and consent recording with ip_address, see the Create Verification API reference. For privacy-notice requirements and legacy consent behavior, see Consents.
For webhook delivery, retries, and signature verification, see the Webhooks guide.
Verification object
The Verification object is returned by POST /verifications (initial state), by the verification.completed webhook (final state), and by GET /verifications/{verification_id} (any state).
| Field Name | Type | Description | Example |
|---|---|---|---|
id | string (UUID) | Unique verification identifier. Auto-generated. | "bd830637-ea6e-4888-80ab-a09f01fc9209" |
identifier | string | CURP (individual) or 12-char RFC (business) being verified. | "OICE940722HGFRST08" |
status | string | Verification state. One of "in_progress", "completed". | "completed" |
data_available | boolean | Whether any data was found for the identifier. | true |
can_retry | boolean | Whether the verification can be retried. | false |
entities | array[string] | Data entities available for the identifier. See Entities below. | ["profile", "invoices"] |
consent_id | string (UUID) | Identifier of the consent used for this verification. When you send ip_address, a new consent is recorded for this verification. | "92d78902-61e0-4fc1-93e6-243519259cb3" |
external_id | string or null | Optional external identifier passed at creation, used to correlate with your internal systems. | "USER_67890_VERIFICATION_001" |
created_at | string (ISO 8601) | When the verification was created. | "2025-09-25T19:42:48.269024Z" |
Entities
The entities array tells you which data endpoints have data for this identifier. Only retrieve from endpoints listed here, otherwise you'll get 404.
For Individuals (CURP)
| Entity | Endpoint | Description |
|---|---|---|
profile | GET /profile/{identifier} | Personal identity and address. For income, employment status and tenure, use GET /estimates. |
invoices | GET /invoices/{identifier} | CFDI invoices issued or received. |
employment | GET /employments/{identifier} | IMSS / ISSSTE employment history. |
employment_files | GET /employment-files/{identifier} | Downloadable IMSS / ISSSTE PDFs. |
earnings | GET /earnings/{identifier} | Platform economy earnings (Uber, DiDi). |
See Profile for the field reference.
For Businesses (12-char RFC)
| Entity | Endpoint | Description |
|---|---|---|
business_profile | GET /business-profile/{identifier} | Legal name, commercial name, RFC. |
invoices | GET /invoices/{rfc} | CFDI invoices issued or received by the business. |
See Business Data for the field reference.
Reacting to completion
When the verification.completed webhook arrives, use this logic to decide what to do:
status == "completed"anddata_available == true: iterate overentitiesand fetch data from each corresponding endpoint.status == "completed"anddata_available == false: no data was found for the identifier. Checkcan_retry.can_retry == true: the upstream source was unavailable or returned no result. You can create a new verification with the same identifier later.can_retry == false: the verification is final. Creating another one will return the same result.
The is_billable flag in the Verification object (returned by GET /verifications/{verification_id}) indicates whether this verification counts toward billing.
Updated 25 days ago
