Verified residency from any supporting document.

You are integrating Didit's Proof of Address into a regulated onboarding flow (bank, fintech, lender, crypto exchange, EU payment institution). Regulators want a current address on every customer file; the legacy "ask the user to type it" approach fails audit because the typed address is unverified.

Four obligations on every Proof of Address:

  1. Capture an acceptable document — utility bill, bank statement, government letter, lease, mortgage, mobile / internet contract — dated within the last 90 days.
  2. Read the address fields with Optical Character Recognition (OCR) and parse them into the canonical address envelope (line 1, line 2, city, postal code, country).
  3. Cross-check the address against the address on the underlying ID document AND against the name on both — a mismatched address or a mismatched name fails the check.
  4. Where the country supports it, validate the parsed address against the authoritative address registry (UK Royal Mail PAF, Spain Catastro / Padrón, France BAN, Germany DATEV, US USPS).

Pricing (verified live):
  - Proof of Address: $0.20 per check
  - ID Verification (required as the cross-check anchor): $0.15 per check
  - Database Validation (per-country registry validation, optional): variable per service
  - Combined bundle (ID + Liveness + Face Match + Proof of Address): $0.55 per user
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder bundling ID Verification + Passive Liveness + Face Match 1:1 + Proof of Address. Add a Database Validation node for the country-specific address registry where available.

STEP 1 — Create the session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your proof-of-address workflow id>",
      "vendor_data": "<your user id, max 256 chars>",
      "callback_url": "https://<your-app>/onboarding/poa/callback",
      "expected_country": "ES",
      "metadata": {
        "purpose": "regulatory_address_capture",
        "user_id": "<your internal id>"
      }
    }

  Response: 201 Created with the hosted session URL. SMS or email the URL to the user; they complete ID capture + selfie + Proof of Address upload on their phone in under five minutes.

STEP 2 — Read the signed webhook on completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "id_verification": { "status": "Approved", "document_type": "passport", "country_code": "ES" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "proof_of_address": {
        "status": "Approved",
        "document_type": "utility_bill",
        "issuer": "Iberdrola",
        "issued_at": "2026-04-12",
        "address": {
          "line1": "C. Diagonal 612",
          "line2": "3a",
          "city": "Barcelona",
          "postal_code": "08021",
          "country": "ES"
        },
        "cross_check": {
          "name_match": true,
          "address_match_with_id": true,
          "within_90_day_window": true
        }
      },
      "database_validation": {
        "status": "Approved",
        "service": "es_catastro_address",
        "result": { "registry_match": true }
      }
    }

  Session status enum (exact case):
    Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 3 — Decide

  Branch logic:
    Approved    → file the canonical address payload on the customer record.
    In Review   → hold the onboarding, wait for analyst webhook update.
    Declined    → refuse onboarding, log the decline reason (typically: document over 90 days old, name mismatch, address mismatch with the ID).
    Resubmitted → user updated the upload; re-read the decision.

  The Proof of Address sub-result is independent of the parent session — even if the parent session is Approved, the proof_of_address.status might be In Review if the cross-check flagged a different city. Switch on proof_of_address.status when you persist the address.

STEP 4 — Persist the canonical address envelope

  When proof_of_address.status === "Approved", save the entire address object to your customer record as the regulatory current address. Use the canonical fields (line1, line2, city, postal_code, country) — Didit normalises across document layouts so the same shape works for an English utility bill, a Spanish bank statement, and a German Anmeldung.

  Keep the issuer + issued_at fields for your audit log — they prove the document type and the recency window the regulator audited.

STEP 5 — Registry validation result

  When the workflow includes a Database Validation node, the database_validation block returns the per-country registry-validation outcome:
    - es_catastro_address — Spanish Catastro property registry
    - uk_royal_mail_paf — UK Postcode Address File
    - fr_ban — France Base Adresse Nationale
    - de_anmeldung — German municipal registration check
    - us_usps — US Postal Service address validation

  A registry-match-false result on a country that supports validation is a signal worth manual review even if the OCR pass succeeded — most fake addresses fail registry validation immediately.

STEP 6 — Refresh on a cadence (optional)

  Most regulators ask for the address on file to be re-confirmed every 1-3 years (longer for low-risk customers, shorter for high-risk). Add a periodic Proof of Address session to your account-refresh cadence — same workflow, same hosted URL flow.

WEBHOOK EVENT NAMES
  - status.updated — session status changed.
  - data.updated — session data changed (resubmission, document re-upload).

  Verify X-Signature-V2 on every payload. The webhook secret is per-environment — sandbox key is separate from production.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review).
  - Acceptable documents must be dated within the last 90 days by default; some workflows extend to 180 days for low-risk customer segments.
  - The address on the Proof of Address document MUST cross-check against the address on the underlying ID OR against a previously-Approved address on file. If neither match, the proof flips to In Review automatically.
  - Default record retention is 5 years post-relationship per the EU AML package.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/core-technology/proof-of-address/overview
  - https://docs.didit.me/core-technology/database-validation/overview
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.