Verifications

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 /verifications with an identifier. The API resolves the matching consent automatically — a valid consent must already exist for the identifier.
In progress. The verification is queued and processed asynchronously. The initial response returns status: "in_progress" and the consent_id used.
Completed. When processing finishes, BDI sends a verification.completed webhook to your registered endpoint. The webhook payload reflects the final state, including which data entities are available.
Fetch data. Once completed and data_available is true, retrieve the relevant data from the resource endpoints listed in entities.

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 optional context fields (rfc, phone, email), and the consent resolution logic, see the Create Verification API reference.

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)	Consent used for this verification. Resolved automatically from the existing consents.	`"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, address, employment status, estimated income.
`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 Individual Data 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" and data_available == true: iterate over entities and fetch data from each corresponding endpoint.
status == "completed" and data_available == false: no data was found for the identifier. Check can_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.