### 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

### 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

---

## Utility Scripts

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

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,
});

{
  "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"
}

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

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

# 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