API подтверждения адреса: верификация POA и 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"
}

Авторизации

x-api-key

string

header

обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

multipart/form-data

document

file

обязательно

Документ «Подтверждение адреса». Допустимые расширения: tiff, jpg, jpeg, png, pdf, webp. Максимальный размер загружаемого файла: 15 MB (файлы большего размера отклоняются с ошибкой 400). Поддерживаются многостраничные PDF (ожидается более высокая задержка); для зашифрованных PDF требуется document_password. Изображения автоматически сжимаются перед обработкой.

document_password

string

write-only

Пароль для расшифровки document, если это зашифрованный PDF-файл. Передача зашифрованного PDF без пароля (или с неверным паролем) возвращает 400.

expected_address

string

Адрес для сверки с документом. Он геокодируется и сравнивается с извлечённым адресом; несоответствие (или ожидаемый адрес, который не удаётся геокодировать/проверить) добавляет ADDRESS_MISMATCH_WITH_PROVIDED, управляемое poa_address_mismatch_action. Геокодированная форма возвращается в expected_details_formatted_address / expected_details_parsed_address.

Пример:

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

expected_country

string

Страна для сверки с документом (код ISO 3166-1, например ARG или AR). Несовпадение со страной документа добавляет POA_COUNTRY_MISMATCH_WITH_PROVIDED, регулируемое poa_address_mismatch_action.

Пример:

"ARG"

expected_first_name

string

Имя для сверки с name_on_document (нечёткое сравнение с учётом транслитерации). Оценка ниже порога совпадения добавляет NAME_MISMATCH_WITH_PROVIDED, регулируемый параметром poa_address_mismatch_action.

Пример:

"Sophia"

expected_last_name

string

Фамилия для сверки с name_on_document, объединяемая с expected_first_name для расчёта оценки совпадения.

Пример:

"Martinez"

poa_languages_allowed

string

Разделённый запятыми список принимаемых языков документов в виде кодов ISO 639-1 (например, en,es,fr). Если параметр опущен или пуст, принимаются все 51 поддерживаемый язык. Документ на языке вне этого списка добавляет UNSUPPORTED_DOCUMENT_LANGUAGE (регулируется параметром poa_unsupported_language_action); неизвестный код в списке возвращает 400 с полным набором поддерживаемых кодов.

Пример:

"en,es"

poa_document_age_months

string

Разделённые запятыми пары key:value, задающие максимальный возраст документа в месяцах для каждого типа документа — ключи: utility_bill, bank_statement, government_issued_document, other_poa_document; значения: 1–120 или -1 для неограниченного срока (без проверки возраста). Значения по умолчанию, если параметр опущен: utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12. Документ старше установленного лимита отклоняется с POA_DOCUMENT_EXPIRED. Внимание: если вы передаёте это поле, укажите каждый принимаемый вами тип — пропущенные типы считаются неприемлемыми (информационный статус POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION), а проверка их возраста пропускается.

Пример:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action

enum<string>

по умолчанию:DECLINE

Принимается, но в настоящее время не применяется — предупреждения о несоответствии имени (NAME_MISMATCH_WITH_PROVIDED) вместо этого регулируются параметром poa_address_mismatch_action. Задайте poa_address_mismatch_action, чтобы управлять поведением при несоответствии как имени, так и адреса.

Доступные опции:

DECLINE,

NO_ACTION

poa_document_issues_action

enum<string>

по умолчанию:DECLINE

Действие при проблемах с целостностью файла — на практике этот endpoint генерирует только DOCUMENT_METADATA_MISMATCH.

Доступные опции:

DECLINE,

NO_ACTION

poa_document_authenticity_action

enum<string>

по умолчанию:DECLINE

Действие при подозрении на манипуляцию с документом (SUSPECTED_DOCUMENT_MANIPULATION) — например, PDF был изменён после цифровой подписи, обработан известным PDF-редактором, имеет признаки манипуляций с наложением текста или содержит несогласованные даты EXIF. Также управляет POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT (повторно набранное текстовое поле, изменение которого невозможно подтвердить или опровергнуть): при DECLINE оно также отклоняется, при NO_ACTION остаётся предупреждением.

Доступные опции:

DECLINE,

NO_ACTION

poa_unsupported_language_action

enum<string>

по умолчанию:DECLINE

Что делать, если язык документа не входит в poa_languages_allowed (UNSUPPORTED_DOCUMENT_LANGUAGE).

Доступные опции:

DECLINE,

NO_ACTION

poa_address_mismatch_action

enum<string>

по умолчанию:DECLINE

Что делать, если извлеченные данные не совпадают с полями expected_*: предупреждения ADDRESS_MISMATCH_WITH_PROVIDED, NAME_MISMATCH_WITH_PROVIDED и POA_COUNTRY_MISMATCH_WITH_PROVIDED следуют этому действию.

Доступные опции:

DECLINE,

NO_ACTION

poa_issuer_not_identified_action

enum<string>

по умолчанию:DECLINE

Действие, если в документе не удаётся определить выдавшую компанию/организацию (ISSUER_NOT_IDENTIFIED).

Доступные опции:

DECLINE,

NO_ACTION

save_api_request

boolean

по умолчанию:true

Если true (по умолчанию), сохраняет вызов как сессию типа API — видимую в Business Console, доступную через GET /v3/session/{sessionId}/decision/ по возвращенному request_id, анонсируемую через webhook status.updated, с сохранением загруженного документа. Если false, ничего не сохраняется, а request_id является временным UUID только для сопоставления ответа.

Пример:

true

vendor_data

string

Необязательная непрозрачная строка (ваш внутренний идентификатор пользователя, email, UUID…), сохраняемая в сессии и возвращаемая в ответе. Используйте её для сопоставления вызовов API с вашими собственными записями и для последующей фильтрации сессий.

Пример:

"user-123"

metadata

object

Необязательный объект JSON, сохраняемый вместе с сессией (когда save_api_request=true) и возвращаемый обратно в ответе. В multipart-запросах отправляйте его как строковое поле в формате JSON (например, metadata={"flow":"onboarding"}) — он парсится в объект.

Пример:

{ "flow": "onboarding" }

Ответ

Документ обработан. Значение poa.status: Approved или Declined; каждая обнаруженная проблема детализирована в poa.warnings. Для истёкшего, несовпадающего или подозрительного документа по-прежнему возвращается 200 со статусом status: "Declined" — проверяйте тело ответа, а не только HTTP-код. Если save_api_request=true, request_id представляет собой сохранённый id сессии.

request_id

string<uuid>

Идентификатор сохраненной сессии при save_api_request=true (доступен для использования с GET /v3/session/{sessionId}/decision/); в противном случае это временный корреляционный UUID.

poa

object

Show child attributes

vendor_data

string | null

Эхо-значение переданного вами vendor_data или null.

metadata

object | null

Эхо-значение переданного вами объекта metadata или null.

created_at

string<date-time>

Временная метка ISO 8601 (UTC) момента генерации ответа.

Последнее изменение 7 ноября 2026 г.