어떤 신원이든 교차 확인하세요.
발급 기관의 원본 데이터와 대조합니다.

# Didit Database Validation — integrate in 5 minutes

You are integrating Didit's Database Validation module into <my_stack>.
Database Validation cross-references each user's identity data against the
authoritative source for that country — the national civil registry, tax
authority, electoral roll, credit bureau, telco database, court record or
biometric service that issued the document. 1,000+ data sources reachable
through one endpoint. Follow these steps exactly. Every URL, header, and
enum value below is canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI)
Best when you want Didit to capture the ID document, run Optical Character Recognition (OCR), derive the
required fields automatically, and trigger the right registry service per
issuing country.

1. Create a workflow that contains the DATABASE_VALIDATION feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array including
         { feature: "DATABASE_VALIDATION" }   (UPPERCASE — strict enum)
   Configure per-country service IDs (e.g. arg_renaper, bra_cpf,
   mex_curp, dom_cedula) plus partialMatchAction / noMatchAction.

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id).
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already have the identity fields (mobile SDK capture,
existing onboarding pipeline, reseller flow). Single endpoint, every
country and every service routed through it.

POST https://verification.didit.me/v3/database-validation/
Content-Type: multipart/form-data
Body fields (all optional except issuing_state and at least one identifier):
  - issuing_state           (required, ISO 3166-1 alpha-3, e.g. ARG, BRA, MEX)
  - services                (optional, repeated, service IDs to run; omit
                             to run every configured service for that country)
  - identification_number   (e.g. DNI, CPF, CURP, cedula number)
  - first_name
  - last_name
  - date_of_birth           (YYYY-MM-DD)
  - selfie                  (file, required for biometric services such as
                             arg_renaper, pan_cedula_sib, pan_cedula_sib_plus)
  - address_element_1       (street + number)
  - address_element_2       (unit / building / floor)
  - address_element_3       (suburb / district)
  - address_element_4       (city / state / region)
  - address_element_5       (postal code; postal_code alias accepted)
  - consent                 (boolean — required when the selected service
                             has requires_consent=true in the catalog)
  - vendor_data             (optional string, your user id)

Response: JSON report with match_type, validation_type (1x1 or 2x2),
per-service validations, source_data, and any warnings.

## 3. Webhooks (Path A only — Path B returns synchronously)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 4. Reading the report (both paths return the same shape)
The database_validation object includes:
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- match_type: "full_match" | "partial_match" | "no_match"
- issuing_state: ISO 3166-1 alpha-3 country code
- validation_type: "1x1" (single source full-match) or "2x2" (two
  independent sources corroborate the data)
- screened_data: the user fields submitted (identification_number,
  first_name, last_name, date_of_birth, selfie, address fields, ...)
- validations: array of per-service results. Each entry carries
  service_id (e.g. arg_renaper), service_name, outcome_code (MATCH,
  NO_MATCH, DOCUMENT_NOT_FOUND, BIOMETRIC_IMAGE_UNUSABLE,
  REGISTRY_UNAVAILABLE, ...), optional outcome_detail, a per-field
  validation block (full_match / partial_match / no_match), and a
  source_data block lifted from the registry record (photo, signature,
  full_name, gender, dates, face_match_score for biometric services).

Configurable risks (action per workflow — Decline, Review, or Approve):
- DATABASE_VALIDATION_PARTIAL_MATCH    (partialMatchAction)
- DATABASE_VALIDATION_NO_MATCH         (noMatchAction)

Warnings raised when a service cannot run:
- COULD_NOT_PERFORM_DATABASE_VALIDATION — required input field missing
  (e.g. CPF could not be OCR-extracted). You are NOT charged. Session
  auto-moves to In Review; saving the missing field in the Console
  retriggers the check.

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: DATABASE_VALIDATION, ID_VERIFICATION,
  LIVENESS, FACE_MATCH, AML, IP_ANALYSIS.
- Country codes are ISO 3166-1 alpha-3 UPPERCASE: ARG, BRA, MEX, ESP, ...
- Service IDs are lowercase snake-case with a country prefix:
  arg_renaper, bra_cpf, mex_curp, dom_cedula, pan_cedula_sib_plus, ...
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- match_type casing matches exactly: full_match, partial_match, no_match
  (lowercase snake-case).
- You are only billed when a service returns a result. Skipped services
  (missing input, unsupported issuing_state) are never billed.

## 6. Pricing reference (public, pay-per-call)
- Variable per source. Lowest tier: $0.05 per check (Dominican Republic,
  Junta Central Electoral).
- Standard government-registry tier: $0.20 per check (Argentina RENAPER,
  Brazil Receita Federal CPF, Mexico RENAPO CURP, Spain DGP, Colombia
  Registraduria, Peru RENIEC, Chile Registro Civil, Ecuador, Uruguay,
  El Salvador, Guatemala, Honduras, Bolivia, Paraguay, Venezuela, Costa
  Rica).
- Biometric premium tier: $0.75 (Panama SIB) up to $1.50 (Panama SIB
  Plus elevated tier with stronger biometric thresholds).
- Global identity network: 156 datasets across 45 countries (AU, NZ,
  UK, IE, FR, DE, IT, ES, PT, NL, BE, CH, AT, Nordics, Greece, Poland,
  Czechia, Hungary, Romania, Slovakia, India, Indonesia, Philippines,
  Thailand, Malaysia, Singapore, Hong Kong, China, Cambodia, Kenya,
  Nigeria, South Africa, Morocco, USA, Canada). Per-service pricing
  surfaced in the catalog and billing exports.
- 500 free checks every month, forever, on every account.

## 7. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test the full catalog of services with the per-country reference pages
  under https://docs.didit.me/api-reference/database-validation/.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/database-validation/overview