Proof of Address API: POA Verification & OCR

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

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.proof_of_address.verify(
    document=open("document.pdf", "rb"),
    expected_address="Av. Monseñor Tavella 1291, Salta, Argentina",
    expected_country="ARG",
    expected_first_name="Sophia",
    expected_last_name="Martinez",
    poa_languages_allowed="en,es",
    save_api_request=True,
    vendor_data="user-123",
)
print(result)

import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.proofOfAddress.verify({
  document: await fileFromPath("document.pdf"),
  expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
  expected_country: "ARG",
  expected_first_name: "Sophia",
  expected_last_name: "Martinez",
  poa_languages_allowed: "en,es",
  save_api_request: true,
  vendor_data: "user-123",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
	Document:            didit.FileFromPath("document.pdf"),
	ExpectedAddress:     didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
	ExpectedCountry:     didit.String("ARG"),
	ExpectedFirstName:   didit.String("Sophia"),
	ExpectedLastName:    didit.String("Martinez"),
	POALanguagesAllowed: didit.String("en,es"),
	SaveAPIRequest:      didit.Bool(true),
	VendorData:          didit.String("user-123"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.ProofOfAddressVerifyParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()
        .document(Path.of("document.pdf"))
        .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina")
        .expectedCountry("ARG")
        .expectedFirstName("Sophia")
        .expectedLastName("Martinez")
        .poaLanguagesAllowed("en,es")
        .saveApiRequest(true)
        .vendorData("user-123")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->proofOfAddress->verify([
    'document' => File::fromPath('document.pdf'),
    'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',
    'expected_country' => 'ARG',
    'expected_first_name' => 'Sophia',
    'expected_last_name' => 'Martinez',
    'poa_languages_allowed' => 'en,es',
    'save_api_request' => true,
    'vendor_data' => 'user-123',
]);
print_r($result->toArray());

require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.proof_of_address.verify(
  document: Pathname("document.pdf"),
  expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
  expected_country: "ARG",
  expected_first_name: "Sophia",
  expected_last_name: "Martinez",
  poa_languages_allowed: "en,es",
  save_api_request: true,
  vendor_data: "user-123"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams
{
    Document = FileUpload.FromPath("document.pdf"),
    ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina",
    ExpectedCountry = "ARG",
    ExpectedFirstName = "Sophia",
    ExpectedLastName = "Martinez",
    PoaLanguagesAllowed = "en,es",
    SaveApiRequest = true,
    VendorData = "user-123",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "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"
      ]
    },
    "detected_codes": [
      {
        "type": "QR_CODE",
        "page_number": 1,
        "position": [
          [
            820,
            1120
          ],
          [
            1002,
            1120
          ],
          [
            1002,
            1302
          ],
          [
            820,
            1302
          ]
        ],
        "x": 820,
        "y": 1120,
        "width": 182,
        "height": 182,
        "page_width": 1190,
        "page_height": 1684,
        "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==",
        "parsed_payload": "https://aguasdelnorte.com/factura/998811"
      },
      {
        "type": "CODE_128",
        "page_number": 1,
        "position": [
          [
            112,
            1480
          ],
          [
            560,
            1480
          ],
          [
            560,
            1540
          ],
          [
            112,
            1540
          ]
        ],
        "x": 112,
        "y": 1480,
        "width": 448,
        "height": 60,
        "page_width": 1190,
        "page_height": 1684,
        "raw_payload": "MDA5OTg4MTEwMDA0Mg==",
        "parsed_payload": "0099881100042"
      }
    ],
    "status": "Approved",
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T02:29:02.439655+00:00"
}

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

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.proof_of_address.verify(
    document=open("document.pdf", "rb"),
    expected_address="Av. Monseñor Tavella 1291, Salta, Argentina",
    expected_country="ARG",
    expected_first_name="Sophia",
    expected_last_name="Martinez",
    poa_languages_allowed="en,es",
    save_api_request=True,
    vendor_data="user-123",
)
print(result)

import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.proofOfAddress.verify({
  document: await fileFromPath("document.pdf"),
  expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
  expected_country: "ARG",
  expected_first_name: "Sophia",
  expected_last_name: "Martinez",
  poa_languages_allowed: "en,es",
  save_api_request: true,
  vendor_data: "user-123",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
	Document:            didit.FileFromPath("document.pdf"),
	ExpectedAddress:     didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
	ExpectedCountry:     didit.String("ARG"),
	ExpectedFirstName:   didit.String("Sophia"),
	ExpectedLastName:    didit.String("Martinez"),
	POALanguagesAllowed: didit.String("en,es"),
	SaveAPIRequest:      didit.Bool(true),
	VendorData:          didit.String("user-123"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.ProofOfAddressVerifyParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()
        .document(Path.of("document.pdf"))
        .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina")
        .expectedCountry("ARG")
        .expectedFirstName("Sophia")
        .expectedLastName("Martinez")
        .poaLanguagesAllowed("en,es")
        .saveApiRequest(true)
        .vendorData("user-123")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->proofOfAddress->verify([
    'document' => File::fromPath('document.pdf'),
    'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',
    'expected_country' => 'ARG',
    'expected_first_name' => 'Sophia',
    'expected_last_name' => 'Martinez',
    'poa_languages_allowed' => 'en,es',
    'save_api_request' => true,
    'vendor_data' => 'user-123',
]);
print_r($result->toArray());

require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.proof_of_address.verify(
  document: Pathname("document.pdf"),
  expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
  expected_country: "ARG",
  expected_first_name: "Sophia",
  expected_last_name: "Martinez",
  poa_languages_allowed: "en,es",
  save_api_request: true,
  vendor_data: "user-123"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams
{
    Document = FileUpload.FromPath("document.pdf"),
    ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina",
    ExpectedCountry = "ARG",
    ExpectedFirstName = "Sophia",
    ExpectedLastName = "Martinez",
    PoaLanguagesAllowed = "en,es",
    SaveApiRequest = true,
    VendorData = "user-123",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "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"
      ]
    },
    "detected_codes": [
      {
        "type": "QR_CODE",
        "page_number": 1,
        "position": [
          [
            820,
            1120
          ],
          [
            1002,
            1120
          ],
          [
            1002,
            1302
          ],
          [
            820,
            1302
          ]
        ],
        "x": 820,
        "y": 1120,
        "width": 182,
        "height": 182,
        "page_width": 1190,
        "page_height": 1684,
        "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==",
        "parsed_payload": "https://aguasdelnorte.com/factura/998811"
      },
      {
        "type": "CODE_128",
        "page_number": 1,
        "position": [
          [
            112,
            1480
          ],
          [
            560,
            1480
          ],
          [
            560,
            1540
          ],
          [
            112,
            1540
          ]
        ],
        "x": 112,
        "y": 1480,
        "width": 448,
        "height": 60,
        "page_width": 1190,
        "page_height": 1684,
        "raw_payload": "MDA5OTg4MTEwMDA0Mg==",
        "parsed_payload": "0099881100042"
      }
    ],
    "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

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

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. Also governs POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT (a re-typed text field the file cannot prove changed or unchanged): DECLINE declines it too, NO_ACTION keeps it as a warning.

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

Echo of the metadata object you sent, or null.

created_at

string<date-time>

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

Last modified on November 1, 2026