Didit Proof Of Address

Integrate Didit Proof of Address standalone API to verify address documents. Use when the user wants to verify a proof of address, validate utility bills, ba...

Security Scan

The skill's requirements, instructions, and included script are consistent with a Proof-of-Address integration that simply needs a Didit API key to upload documents for verification; nothing in the package indicates covert or unrelated access.

Purpose & Capability

Name/description ask to integrate Didit PoA and the skill only requests DIDIT_API_KEY and targets Didit endpoints. The included script and SKILL.md only interact with verification.didit.me and the Didit docs domain, which is proportionate to the stated purpose.

Instruction Scope

SKILL.md and scripts instruct uploading documents to Didit using the x-api-key header and do not access unrelated files or environment variables. Minor mismatch: the example script prints fields from an 'address' key that the SKILL.md response sample represents under 'poa' (e.g., 'poa_parsed_address' / 'poa_address'), so the script may not display all returned fields as expected. Privacy note: the workflow necessarily uploads personal documents (PII) to an external service — users should be aware of data-handling and retention (SKILL.md's default save_api_request=true means requests may be stored in the Business Console).

Install Mechanism

No install spec (instruction-only plus a small helper script). No downloads, package installs, or archives — minimal surface area and nothing being written or executed beyond the included script.

Credentials

Only a single credential (DIDIT_API_KEY) is declared and used. That single API key is appropriate and necessary for the described API interactions; no unrelated secrets or config paths are requested.

Persistence & Privilege

always is false and the skill does not request permanent or elevated platform privileges. The skill does not attempt to modify other skills or system settings.

Assessment

This skill appears to do what it says: it uploads documents to Didit using a DIDIT_API_KEY. Before installing or using it: (1) only provide a DIDIT_API_KEY you control and store it securely (do not paste into public logs); (2) be aware that uploading documents contains sensitive PII — confirm retention and privacy practices with Didit and whether save_api_request (default true) is acceptable; (3) review that the endpoint verification.didit.me is the intended service for your account; and (4) test with non-production/sample documents first. The helper script has a small display mismatch with the SKILL.md response format (may not show all returned fields), but this is a functional/quality issue, not evidence of malicious behavior.

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": "[e-mail]", "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": "[e-mail]", "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

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())

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)

{
  "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 60 min)
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.

# 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