Thibitisha anwani yoyote.
Kutoka kwa bili, benki, au barua.

# Didit Proof of Address — integrate in 5 minutes

You are integrating Didit's Proof of Address (PoA) module into <my_stack>.
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 handle document capture, multi-page upload,
auto-capture, mobile handoff, and accessibility for you.

1. Create a workflow that contains the PROOF_OF_ADDRESS feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the single entry
         { feature: "PROOF_OF_ADDRESS" }   (UPPERCASE — strict enum)
   Optional config: accepted document_type filters
   (UTILITY_BILL, BANK_STATEMENT, GOVERNMENT_ISSUED_DOCUMENT,
   OTHER_POA_DOCUMENT) and per-warning threshold overrides.

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 a captured document image or PDF (mobile SDK
capture, native onboarding app, reseller pipeline).

POST https://verification.didit.me/v3/poa/
Content-Type: multipart/form-data
Body fields:
  - document     (required, file — JPG, JPEG, PNG, TIFF, or PDF, <= 15 MB)
  - vendor_data  (optional string, your user id)
  - full_name    (optional string, name to cross-check against the document)
  - address      (optional string, address to cross-check against the document)

Response: JSON report with the parsed address, document_type, issuer,
issue_date, name_on_document, and a warnings array.

## 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 poa object includes:
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- issuing_state: ISO 3166-1 alpha-3 country code
- document_type: "UTILITY_BILL" | "BANK_STATEMENT" |
                 "GOVERNMENT_ISSUED_DOCUMENT" | "OTHER_POA_DOCUMENT" |
                 "UNKNOWN"
- issuer: string (the issuing institution or company)
- issue_date: YYYY-MM-DD
- expiration_date: YYYY-MM-DD or null
- document_language: ISO 639-1 language code
- name_on_document: string (full name extracted from the document)
- poa_address: raw extracted address string
- poa_formatted_address: normalized human-readable address string
- poa_parsed_address: structured object with street_1, street_2, city,
  region, postal_code, address_type, and raw_results.geometry.location
  (lat / lng for geocoding)
- document_file: signed URL to the captured document (expires in 60 minutes)
- document_metadata: optional file_size, content_type, creation_date,
  modified_date, and overlay_manipulation forensic block for PDFs (detected
  flag, signals such as duplicate_font_subset or glyph_fragmentation, and
  manipulated_regions in PDF page coordinates)
- warnings: Array<{ risk, additional_data, log_type, short_description,
                    long_description }>

Auto-decline risks (always enforced by Didit, not configurable):
- POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION
- EXPIRED_DOCUMENT
- INVALID_DOCUMENT_TYPE
- MISSING_ADDRESS_INFORMATION

Configurable risks (action per workflow — Decline, Review, or Approve):
- NAME_MISMATCH_WITH_PROVIDED
- NAME_MISMATCH_ID_VERIFICATION
- POA_NAME_MISMATCH_BETWEEN_DOCUMENTS
- POOR_DOCUMENT_QUALITY
- DOCUMENT_METADATA_MISMATCH
- SUSPECTED_DOCUMENT_MANIPULATION
- UNSUPPORTED_DOCUMENT_LANGUAGE
- ADDRESS_MISMATCH_WITH_PROVIDED
- UNABLE_TO_EXTRACT_ISSUE_DATE
- UNPARSABLE_OR_INVALID_ADDRESS
- ISSUER_NOT_IDENTIFIED
- UNABLE_TO_VALIDATE_DOCUMENT_AGE
- FUTURE_ISSUE_DATE

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: PROOF_OF_ADDRESS, ID_VERIFICATION, LIVENESS,
  FACE_MATCH, AML, IP_ANALYSIS.
- document_type enum is UPPERCASE_SNAKE: UTILITY_BILL, BANK_STATEMENT,
  GOVERNMENT_ISSUED_DOCUMENT, OTHER_POA_DOCUMENT, UNKNOWN.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- Documents must be issued within 90 days of submission — older documents
  trigger the EXPIRED_DOCUMENT auto-decline regardless of policy.
- The PoA document must be different from the document submitted for ID
  Verification — same image triggers POA_DOCUMENT_NOT_SUPPORTED.

## 6. Accepted document types (do not paraphrase to users)
- Utility Bill — Electricity, Water, Gas, Internet, Phone, Cable TV,
  Satellite TV, Trash Collection, Sewage, Heating, Combined Utilities,
  Municipal Services.
- Bank Statement — Account Statement, Credit Card Statement, Bank Letter
  Confirming Address, Mortgage Statement, Loan Statement, Savings,
  Checking, Investment, Business Account, Credit Union, Debit Card,
  Line of Credit.
- Government-Issued Document — Tax Assessment, Voter Registration Card,
  ID document, Residency Certificate, Government Letter, Census Letter,
  Property Tax Bill, Vehicle Registration, Social Security Statement,
  Unemployment Benefits Letter, Pension Statement, Court Summons,
  Municipal Permit, Immigration Document.
- Other Proof of Address — Lease Agreement, Rental Agreement, Employer
  Letter Confirming Address, Insurance Policy, School Enrollment Letter,
  Notarized Affidavit, Solicitor Letter, Payroll Stub, Employment
  Verification Letter, Retirement / Brokerage Account Statement.

Image requirements: JPG, JPEG, PNG, TIFF, or PDF. Maximum file size 15 MB.
Full-color, all corners visible, no digital editing, all pages included
for multi-page documents.

## 7. Pricing reference (public)
- Standalone /v3/poa/ call: $0.20 per check.
- Bundled inside a Didit workflow (KYC plus PoA): $0.20 per check on top
  of the bundle base.
- 500 free verifications every month, forever, on every account.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test documents: deterministic synthetic bills returned in sandbox
  (Approved by default; trigger Declined by submitting the canonical
  "expired" test bill from the sandbox sample pack).
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/proof-of-address/overview