Didit Proof of Address API

Overview

Verifies address documents by submitting images or PDFs. Extracts address information, performs authenticity checks, name matching, geocoding, and returns structured data.

Key constraints:

• Supported formats: JPG, JPEG, PNG, TIFF, PDF
• Maximum file size: 15MB
• Document must be within 90 days of issue date
• Full-color, all corners visible, no digital editing
• Must be different from the ID document used for ID verification

Capabilities: OCR extraction, intelligent document classification, name matching with identity documents, issue date validation, geocoding with lat/lng coordinates, language detection, multi-page support.

Accepted document types:

| Category | Examples | |---|---| | Utility Bill | Electricity, water, gas, internet, phone, combined utilities | | Bank Statement | Account statement, credit card, mortgage, loan | | Government-Issued | Tax assessment, residency certificate, voter registration | | Other PoA | Lease, rental agreement, insurance policy, employer letter |

API Reference: https://docs.didit.me/standalone-apis/proof-of-address Feature Guide: https://docs.didit.me/core-technology/proof-of-address/overview

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}
2. Check email for a 6-character OTP code
3. Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "you@gmail.com", "code": "A3K9F2"} → response includes api_key

To add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.

See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).

Endpoint

POST https://verification.didit.me/v3/poa/

Headers

| Header | Value | Required | |---|---|---| | x-api-key | Your API key | Yes | | Content-Type | multipart/form-data | Yes |

Request Parameters (multipart/form-data)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | document | file | Yes | — | PoA document (JPG/PNG/TIFF/PDF, max 15MB) | | save_api_request | boolean | No | true | Save in Business Console | | vendor_data | string | No | — | Your identifier for session tracking |

Example

python
import requests

response = requests.post(
    "https://verification.didit.me/v3/poa/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"document": ("utility_bill.pdf", open("bill.pdf", "rb"), "application/pdf")},
    data={"vendor_data": "user-123"},
)
print(response.json())

typescript
const formData = new FormData();
formData.append("document", documentFile);

const response = await fetch("https://verification.didit.me/v3/poa/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});

Response (200 OK)

json
{
  "request_id": "a1b2c3d4-...",
  "poa": {
    "status": "Approved",
    "issuing_state": "ESP",
    "document_type": "UTILITY_BILL",
    "issuer": "Endesa",
    "issue_date": "2025-01-15",
    "document_language": "es",
    "name_on_document": "Elena Martínez Sánchez",
    "poa_address": "Calle Mayor 10, 28013 Madrid",
    "poa_formatted_address": "Calle Mayor 10, 28013 Madrid, Spain",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "region": "Comunidad de Madrid",
      "postal_code": "28013",
      "raw_results": {
        "geometry": {"location": {"lat": 40.4168, "lng": -3.7038}}
      }
    },
    "document_file": "https://example.com/document.pdf",
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Status Values & Handling

| Status | Meaning | Action | |---|---|---| | "Approved" | Address verified, document valid | Proceed with your flow | | "Declined" | Document invalid or expired | Check warnings for specific reason | | "In Review" | Needs manual review | Check for name mismatch or quality issues | | "Not Finished" | Processing incomplete | Wait or retry |

Error Responses

| Code | Meaning | Action | |---|---|---| | 400 | Invalid request | Check file format, size, parameters | | 401 | Invalid API key | Verify x-api-key header | | 403 | Insufficient credits | Top up at business.didit.me |

Response Field Reference

| Field | Type | Description | |---|---|---| | status | string | "Approved", "Declined", "In Review", "Not Finished" | | issuing_state | string | ISO 3166-1 alpha-3 country code | | document_type | string | "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" | | issuer | string | Issuing institution name | | issue_date | string | YYYY-MM-DD | | document_language | string | Detected language code | | name_on_document | string | Extracted name | | poa_address | string | Raw extracted address | | poa_formatted_address | string | Formatted address | | poa_parsed_address | object | {street_1, street_2, city, region, postal_code} | | poa_parsed_address.raw_results.geometry.location | object | {lat, lng} geocoded coordinates | | document_file | string | Temporary URL (expires 4 hours) | | warnings | array | {risk, log_type, short_description, long_description} |

Warning Tags

Auto-Decline

| Tag | Description | |---|---| | POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION | Document type not accepted for your app | | EXPIRED_DOCUMENT | Document older than 90 days | | INVALID_DOCUMENT_TYPE | Document cannot be processed | | MISSING_ADDRESS_INFORMATION | No valid address could be extracted |

Configurable (Decline / Review / Approve)

| Tag | Description | |---|---| | NAME_MISMATCH_WITH_PROVIDED | Name doesn't match verified identity | | NAME_MISMATCH_ID_VERIFICATION | Name doesn't match ID document | | POA_NAME_MISMATCH_BETWEEN_DOCUMENTS | Names differ between multiple PoA docs | | POOR_DOCUMENT_QUALITY | Insufficient image quality | | DOCUMENT_METADATA_MISMATCH | Digital signature/metadata indicates tampering | | SUSPECTED_DOCUMENT_MANIPULATION | Signs of document manipulation | | UNSUPPORTED_DOCUMENT_LANGUAGE | Document language not supported | | ADDRESS_MISMATCH_WITH_PROVIDED | Address doesn't match provided address | | UNABLE_TO_EXTRACT_ISSUE_DATE | Could not determine issue date | | ISSUER_NOT_IDENTIFIED | Could not identify issuing institution | | UNPARSABLE_OR_INVALID_ADDRESS | Address couldn't be parsed | | UNABLE_TO_VALIDATE_DOCUMENT_AGE | Could not determine document age | | FUTURE_ISSUE_DATE | Issue date is in the future |

Warning severity: error (→ Declined), warning (→ In Review), information (no effect).

Common Workflows

Basic Address Verification

1. POST /v3/poa/ → {"document": utility_bill}
2. If "Approved" → address verified
   If "Declined" → check warnings:
     EXPIRED_DOCUMENT → ask for a more recent document
     MISSING_ADDRESS_INFORMATION → ask for clearer image
     NAME_MISMATCH → verify identity matches

Full KYC with Address

1. POST /v3/id-verification/ → verify identity document
2. POST /v3/passive-liveness/ → verify real person
3. POST /v3/poa/ → verify address
4. System auto-matches name between ID and PoA documents
5. All Approved → identity + address verified

Utility Scripts

verify_address.py: Verify proof of address documents from the command line.

bash
# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/verify_address.py utility_bill.pdf
python scripts/verify_address.py bank_statement.jpg --vendor-data user-123