cURL

curl -X POST 'https://verification.didit.me/v3/poa/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'document=@./utility-bill.pdf' \
  -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \
  -F 'expected_country=ARG' \
  -F 'expected_first_name=Sophia' \
  -F 'expected_last_name=Martinez' \
  -F 'poa_languages_allowed=en,es' \
  -F 'vendor_data=user-123' \
  --max-time 45

{
  "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88",
  "poa": {
    "issuing_state": "ARG",
    "document_type": "UTILITY_BILL",
    "document_subtype": "WATER_BILL",
    "document_language": "es",
    "issuer": "Aguas del Norte",
    "issue_date": "2026-04-10",
    "expiration_date": null,
    "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA",
    "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina",
    "poa_parsed_address": {
      "street_1": "Avenida Monseñor Tavella 1291",
      "street_2": "b",
      "city": "Salta",
      "region": "Salta",
      "country": "AR",
      "postal_code": "A4400",
      "document_location": {
        "latitude": -24.8208682,
        "longitude": -65.4130954
      }
    },
    "expected_details_address": null,
    "expected_details_formatted_address": null,
    "expected_details_parsed_address": null,
    "name_on_document": "OESTE EMBOTELLADORA S.A.",
    "extra_fields": {
      "bank_account_number": null,
      "bank_iban": null,
      "bank_sort_code": null,
      "bank_routing_number": null,
      "bank_swift_bic": null,
      "bank_branch_name": null,
      "bank_branch_address": null,
      "document_phone_number": null,
      "additional_names": [
        "LA EMBOTELLADORA DEL NORTE SA"
      ]
    },
    "status": "Approved",
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T02:29:02.439655+00:00"
}

Identity & Documents

Proof of Address API

Extract and validate a Proof of Address document — utility bills, bank statements, and government-issued documents — in one call. Returns the issuer, issue/expiry dates, the holder name, the raw and parsed/geocoded address, an Approved/Declined status, and a warnings list explaining every issue found.

Latency. Extraction is LLM-based: typical calls take 5–15 seconds, multi-page PDFs up to ~30 seconds. Configure a client timeout of at least 45 seconds and do not retry before the call completes.

How it works. The document (image or PDF, up to 15 MB; encrypted PDFs require document_password) is classified into a document type and subtype (e.g. UTILITY_BILL / WATER_BILL), and the issuer, dates, holder name, and address are extracted with LLM-based extraction. The address is parsed and geocoded into poa_parsed_address. PDF/EXIF forensics screen for tampering — modification after digital signing, known PDF editors, overlay-text manipulation, suspicious re-exports — surfacing SUSPECTED_DOCUMENT_MANIPULATION or DOCUMENT_METADATA_MISMATCH. Document age is validated against poa_document_age_months, and the language against poa_languages_allowed. If you pass expected_address, expected_country, or expected_first_name/expected_last_name, the extracted values are cross-checked and mismatches are flagged.

Decision logic. status is Approved unless at least one warning resolves to a decline. Hard failures always decline: MISSING_ADDRESS_INFORMATION, POA_DOCUMENT_EXPIRED, INVALID_DOCUMENT_TYPE, UNABLE_TO_VALIDATE_DOCUMENT_AGE, plus UNABLE_TO_EXTRACT_ISSUE_DATE and POA_NAME_NOT_DETECTED (not configurable on this endpoint). Five risk groups are configurable per request via the poa_*_action options (DECLINE or NO_ACTION, all defaulting to DECLINE). POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION and UNPARSABLE_OR_INVALID_ADDRESS are informational on this endpoint and never decline. A document that cannot be processed at all returns 400; a readable but problematic document returns 200 with status: "Declined" — always inspect poa.status and poa.warnings, not just the HTTP code.

Billing. Each 200 response consumes one Proof of Address API credit (standalone APIs have no free tier). When the organization’s balance cannot cover the call, the endpoint returns 403 with the not-enough-credits error before any document processing.

Session persistence (save_api_request, default true). When true, the call is persisted as an API-type session: it appears in the Business Console, the uploaded document is stored, the returned request_id is a real session id you can pass to GET /v3/session/{sessionId}/decision/ (the decision additionally exposes document_file and the document_metadata forensics, which this response omits), and a status.updated webhook is emitted. When false, nothing is stored and request_id is a one-off correlation UUID that cannot be looked up later.

Sandbox. Sandbox API keys skip all processing and billing: after request validation (malformed input still returns 400), the endpoint returns a static Approved mock payload (a fictional “Sandbox Power Co.” electricity bill), no session is persisted, and no credits are consumed.

Authentication. Send your application’s API key in the x-api-key header. Missing or invalid credentials return 403 ({"detail": "You do not have permission to perform this action."}) — this API never returns 401.

Rate limit. Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns 429.

Note: FUTURE_ISSUE_DATE and POOR_DOCUMENT_QUALITY exist in workflow sessions but are never produced by this standalone endpoint — a future-dated document is not auto-declined here.

POST

poa

cURL

curl -X POST 'https://verification.didit.me/v3/poa/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'document=@./utility-bill.pdf' \
  -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \
  -F 'expected_country=ARG' \
  -F 'expected_first_name=Sophia' \
  -F 'expected_last_name=Martinez' \
  -F 'poa_languages_allowed=en,es' \
  -F 'vendor_data=user-123' \
  --max-time 45

{
  "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88",
  "poa": {
    "issuing_state": "ARG",
    "document_type": "UTILITY_BILL",
    "document_subtype": "WATER_BILL",
    "document_language": "es",
    "issuer": "Aguas del Norte",
    "issue_date": "2026-04-10",
    "expiration_date": null,
    "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA",
    "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina",
    "poa_parsed_address": {
      "street_1": "Avenida Monseñor Tavella 1291",
      "street_2": "b",
      "city": "Salta",
      "region": "Salta",
      "country": "AR",
      "postal_code": "A4400",
      "document_location": {
        "latitude": -24.8208682,
        "longitude": -65.4130954
      }
    },
    "expected_details_address": null,
    "expected_details_formatted_address": null,
    "expected_details_parsed_address": null,
    "name_on_document": "OESTE EMBOTELLADORA S.A.",
    "extra_fields": {
      "bank_account_number": null,
      "bank_iban": null,
      "bank_sort_code": null,
      "bank_routing_number": null,
      "bank_swift_bic": null,
      "bank_branch_name": null,
      "bank_branch_address": null,
      "document_phone_number": null,
      "additional_names": [
        "LA EMBOTELLADORA DEL NORTE SA"
      ]
    },
    "status": "Approved",
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T02:29:02.439655+00:00"
}

Authorizations

x-api-key

string

header

required

Body

multipart/form-data

document

file

required

The Proof of Address document. Allowed extensions: tiff, jpg, jpeg, png, pdf, webp. Maximum upload size: 15 MB (larger files are rejected with 400). Multi-page PDFs are supported (expect higher latency); encrypted PDFs require document_password. Images are automatically compressed before processing.

document_password

string

write-only

Password to decrypt document when it is an encrypted PDF. Sending an encrypted PDF without (or with a wrong) password returns 400.

expected_address

string

Address to verify against the document. It is geocoded and compared with the extracted address; a mismatch (or an expected address that cannot be geocoded/verified) adds ADDRESS_MISMATCH_WITH_PROVIDED, governed by poa_address_mismatch_action. The geocoded form is echoed back in expected_details_formatted_address / expected_details_parsed_address.

Example:

"Av. Monseñor Tavella 1291, Salta, Argentina"

expected_country

string

Country to verify against the document (ISO 3166-1 code, e.g. ARG or AR). A mismatch with the document's country adds POA_COUNTRY_MISMATCH_WITH_PROVIDED, governed by poa_address_mismatch_action.

Example:

"ARG"

expected_first_name

string

First name to verify against name_on_document (fuzzy match, transliteration-aware). A score below the match threshold adds NAME_MISMATCH_WITH_PROVIDED, governed by poa_address_mismatch_action.

Example:

"Sophia"

expected_last_name

string

Last name to verify against name_on_document, combined with expected_first_name for the match score.

Example:

"Martinez"

poa_languages_allowed

string

Comma-separated list of accepted document languages as ISO 639-1 codes (e.g. en,es,fr). When omitted or blank, all 51 supported languages are accepted. A document in a language outside the list adds UNSUPPORTED_DOCUMENT_LANGUAGE (governed by poa_unsupported_language_action); an unknown code in the list returns 400 with the full set of supported codes.

Example:

"en,es"

poa_document_age_months

string

Comma-separated key:value pairs setting the maximum document age in months per document type — keys: utility_bill, bank_statement, government_issued_document, other_poa_document; values: 1–120, or -1 for unlimited (no age check). Defaults when omitted: utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12. A document older than its limit declines with POA_DOCUMENT_EXPIRED. Caution: when you provide this field, list every type you accept — omitted types are treated as not accepted (informational POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION) and their age check is skipped.

Example:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action

enum<string>

default:DECLINE

Accepted but currently not applied — name-mismatch warnings (NAME_MISMATCH_WITH_PROVIDED) follow poa_address_mismatch_action instead. Set poa_address_mismatch_action to control both name and address mismatch behavior.

Available options:

DECLINE,

NO_ACTION

poa_document_issues_action

enum<string>

default:DECLINE

What to do on file-integrity problems — in practice only DOCUMENT_METADATA_MISMATCH is produced by this endpoint.

Available options:

DECLINE,

NO_ACTION

poa_document_authenticity_action

enum<string>

default:DECLINE

What to do when document manipulation is suspected (SUSPECTED_DOCUMENT_MANIPULATION) — e.g. the PDF was modified after digital signing, processed by a known PDF editor, shows overlay-text manipulation, or has inconsistent EXIF dates.

Available options:

DECLINE,

NO_ACTION

poa_unsupported_language_action

enum<string>

default:DECLINE

What to do when the document language is outside poa_languages_allowed (UNSUPPORTED_DOCUMENT_LANGUAGE).

Available options:

DECLINE,

NO_ACTION

poa_address_mismatch_action

enum<string>

default:DECLINE

What to do when the extracted details disagree with the expected_* fields: ADDRESS_MISMATCH_WITH_PROVIDED, NAME_MISMATCH_WITH_PROVIDED, and POA_COUNTRY_MISMATCH_WITH_PROVIDED all follow this action.

Available options:

DECLINE,

NO_ACTION

poa_issuer_not_identified_action

enum<string>

default:DECLINE

What to do when no issuing company/organization can be identified on the document (ISSUER_NOT_IDENTIFIED).

Available options:

DECLINE,

NO_ACTION

save_api_request

boolean

default:true

When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, announced through a status.updated webhook, and with the uploaded document stored. When false, nothing is stored and request_id is a transient UUID for response correlation only.

Example:

true

vendor_data

string

Optional opaque string (your internal user id, email, UUID…) stored on the persisted session and echoed back in the response. Use it to correlate API calls with your own records and to filter sessions later.

Example:

"user-123"

metadata

object

Optional JSON object stored with the session (when save_api_request=true) and echoed back in the response. In multipart requests, send it as a JSON-encoded string field (e.g. metadata={"flow":"onboarding"}) — it is parsed into an object.

Example:

{ "flow": "onboarding" }

Response

Document processed. poa.status is Approved or Declined; every detected issue is itemized in poa.warnings. An expired, mismatched, or suspicious document still returns 200 with status: "Declined" — inspect the body, not just the HTTP code. When save_api_request=true, request_id is the persisted session id.

request_id

string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

poa

object

Show child attributes

vendor_data

string | null

Echo of the vendor_data you sent, or null.

metadata

object

Echo of the metadata object you sent, or null.

created_at

string<date-time>

ISO 8601 timestamp (UTC) of when the response was generated.

ID Verification API Argentina - DNI verification (RENAPER)

⌘I