Guides

How It Works

The verification lifecycle: create consent, start a verification, receive a webhook, and fetch the data.

Every verification follows the same four-step flow. Use an 18-char CURP for individuals or a 12-char RFC for businesses — the same flow applies to both.

1. Create consent

Required once per identifier per year. Same payload shape for individuals and businesses; only the identifier changes.

Individual (CURP):

POST /consents

{
  "identifier": "CUAI911021MOCRQS09",
  "ip_address": "192.168.2.74",
  "privacy_notice_url": "https://yourdomain.com/privacy"
}

Business (RFC):

POST /consents

{
  "identifier": "MNT850612KR4",
  "ip_address": "192.168.2.74",
  "privacy_notice_url": "https://yourdomain.com/privacy"
}

For the full payload reference, see Consents.


2. Start a verification

Individual (CURP):

POST /verifications

{
  "identifier": "CUAI911021MOCRQS09"
}

Business (RFC):

POST /verifications

{
  "identifier": "MNT850612KR4"
}

The API resolves the matching consent automatically. Initial response returns status: "in_progress" and the consent_id used.


3. Receive a webhook

When processing finishes, BDI sends a verification.completed webhook to your registered endpoint.

Individual webhook:

{
  "event": "verification.completed",
  "verification_id": "01982e40-d53a-7560-8c69-ddb96bd9ca8c",
  "identifier": "CUAI911021MOCRQS09",
  "status": "completed",
  "data_available": true,
  "can_retry": false,
  "entities": ["profile", "invoices", "employment"],
  "last_updated_at": "2025-07-24T10:01:30Z",
  "timestamp": "2025-07-24T10:01:30Z",
  "external_id": null
}

Business webhook:

{
  "event": "verification.completed",
  "verification_id": "5fc3a4d1-7e2b-4d8a-9c0e-1f5b8d2a3e74",
  "identifier": "MNT850612KR4",
  "status": "completed",
  "data_available": true,
  "can_retry": false,
  "entities": ["business_profile", "invoices"],
  "last_updated_at": "2025-07-24T10:02:15Z",
  "timestamp": "2025-07-24T10:02:15Z",
  "external_id": null
}

For delivery, retries, and signature verification, see Webhooks.


4. Fetch the data

Once the webhook arrives with data_available: true, iterate over entities and fetch from each corresponding endpoint.

Individual (CURP):

  • GET /profile/CUAI911021MOCRQS09
  • GET /invoices/CUAI911021MOCRQS09
  • GET /employments/CUAI911021MOCRQS09

Business (RFC):

  • GET /business-profile/MNT850612KR4
  • GET /invoices/MNT850612KR4

For the full Verification object and the entities reference, see Verifications.


Real-time vs batch

Real-time verification

Perfect for loan applications and customer onboarding where you need immediate results:

# Individual (CURP)
curl -X POST https://api.burodeingresos.com/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "CUAI911021MOCRQS09"
  }'

# Business (RFC)
curl -X POST https://api.burodeingresos.com/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "MNT850612KR4"
  }'

Batch processing

Ideal for analyzing existing customer portfolios or processing large datasets:

# Bulk verification request for 3 individuals.
# `identifier` is the 18-char CURP; the optional `rfc` (13 chars for individuals)
# is passed to increase the probability of recovering invoice data.
curl -X POST https://api.burodeingresos.com/verifications/bulk \
  -H "Content-Type: application/json" \
  -d '[
    {"identifier": "CUAI911021MOCRQS09", "rfc": "CUAI911021ABC"},
    {"identifier": "OICE940722HGFRST08", "rfc": "OICE940722DEF"},
    {"identifier": "VAMA850315HVZRRL01", "rfc": "VAMA850315GHI"}
  ]'

Test your integration

Use the Sandbox to validate your integration end to end with fictitious but valid-looking identifiers.


Get API access

Contact us to request a demo account and receive your API key.

Updated 7 days ago