Didit API: запись в списке блокировки и разрешений

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

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

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

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

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

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

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

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

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
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.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

POST

lists

{list_uuid}

entries

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

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

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

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

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

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

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

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

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
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.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

Добавляет запись в список. Значение проверяется по типу записей этого списка:

email: корректный адрес электронной почты
phone: корректный международный номер телефона в формате E.164 (например, +14155552671)
ip_address: корректный IP-адрес или диапазон CIDR (например, 192.168.1.1 или 10.0.0.0/8)
device_fingerprint: не менее 8 символов из букв, цифр, -, _, : и .. Список блокировки отклоняет отпечаток, который сообщили несколько разных устройств, потому что его блокировка привела бы к отклонению заявок от несвязанных с ним людей.
country: корректный код страны по ISO 3166-1 alpha-3 (например, USA, GBR, ESP). Коды alpha-2 (например, US) принимаются и автоматически преобразуются в alpha-3.
user, business: значение vendor_data пользователя или компании
face, document, wallet_address, bank_account, key: любая непустая строка

Все значения записей не учитывают регистр. Отправленные значения нормализуются при сохранении (номера телефонов в E.164, коды стран в верхнем регистре, всё остальное в нижнем) и сравниваются без учёта регистра при верификации. Например, блокировка User@Example.COM также поймает user@example.com. Каждое значение в списке хранится один раз: добавление значения, которое уже есть в списке, возвращает 400.

Для лица используйте Загрузка лица, если у вас есть только изображение, или передайте reference_session_id, чтобы взять лицо из существующей сессии. Запись о лице требует сохранённого лица для сравнения, которое не передаётся в текстовом value.

Добавление из сессии

Когда вы передаёте reference_session_id, Didit:

Находит сессию (она должна принадлежать тому же приложению)
Берёт значение из самой последней записи сессии того типа, который соответствует типу записей списка:
- face: лицо из селфи проверки живости; value содержит UUID лица
- document: номер документа; полное имя, государство выдачи, тип документа, регион и номер документа сохраняются в metadata, а display_label по умолчанию равен имени владельца и номеру документа
- phone: номер телефона
- email: адрес электронной почты
- ip_address: IP-адрес сессии
- device_fingerprint: отпечаток, который идентифицирует одно устройство, с приоритетом устройства, на котором пройден шаг верификации. В списке блокировки Didit отклоняет сессию, в которой есть только отпечаток класса устройства или которая была завершена более чем на одном устройстве: в этом случае передайте точный отпечаток в value.
Связывает запись с сессией (reference_session_id) и с записью (reference_object_uuid) для отслеживания

В системных списках блокировки лиц, документов, телефонов и email запись также помечается как находящаяся в списке блокировки, поэтому новые сессии, которые с ней совпадают, отклоняются. Для любого другого типа записей передавайте также value. Возвращает 400, если сессия не найдена или не содержит данных для запрошенного типа записи.

Лица из селфи при съёмке документа

Пока пользователь фотографирует документ, фронтальная камера может сделать селфи пользователя (изображения front_image_camera_front и back_image_camera_front из отчёта о верификации личности). Это лицо можно добавить в список блокировки лиц наряду с лицом из проверки живости: передайте face_image_source с нужным изображением.

{
  "reference_session_id": "33333333-4444-5555-6666-777777777777",
  "face_image_source": "front_image_camera_front"
}

Запись создаётся только в системном списке блокировки лиц, а value нужно оставить пустым: Didit берёт лицо из селфи сессии.
Селфи должно содержать одно чётко различимое лицо. Если это не так, запрос возвращает 400, и ничего не добавляется.
Каждое селфи можно добавить только один раз. metadata.face_image_source и metadata.reference_node_id показывают, из какого селфи взято лицо.
В сценарии с несколькими шагами верификации личности reference_node_id выбирает шаг, селфи которого нужно использовать. По умолчанию Didit использует самую последнюю верификацию личности, в которой есть это селфи.
С этого момента лицо проверяется так же, как любое другое заблокированное лицо: сравнивается с селфи проверки живости каждой новой сессии и с каждым новым селфи при съёмке документа (см. FRONT_CAMERA_FACE_IN_BLOCKLIST).
Удаление записи убирает лицо из списка блокировки, и оно перестаёт совпадать с новыми сессиями.

Сессии с несколькими записями одного типа

Сессия может содержать несколько записей одного типа, например два номера телефона из многошагового сценария. Didit всегда берёт самую последнюю запись. Если вы передаёте value вместе с reference_session_id, запись сохраняет ваше value, но всё равно связывается с самой последней записью, а в системном списке блокировки помечается именно она. Чтобы добавить значение из более ранней записи, передайте только value, без reference_session_id:

{
  "value": "+34612345678",
  "comment": "First phone number of session 42"
}

Ссылки на транзакции, пользователей и компании

Когда вы добавляете в список блокировки данные из транзакции или пользователя либо компании вендора, передайте UUID этого объекта в reference_object_uuid и укажите тип источника в metadata:

{
  "value": "0x52908400098527886E0F7030069857D2E4169EE7",
  "reference_object_uuid": "55555555-6666-7777-8888-999999999999",
  "metadata": {
    "reference_type": "transaction",
    "reference_id": "55555555-6666-7777-8888-999999999999"
  }
}

Это позволяет перейти от записи списка блокировки к исходной транзакции, пользователю или компании в консоли. Didit сохраняет ключи metadata, которые вы передали, кроме reference_image_url и front_image_url: их устанавливает только Didit. Для записи, прочитанной из сессии, Didit добавляет свои ключи к вашим, и её ключи имеют приоритет.

Источник	`reference_object_uuid`	`metadata.reference_type`
Сессия верификации	Задаёт Didit (запись о лице, документе, телефоне или email)	Не требуется: используйте `reference_session_id`
Транзакция	UUID транзакции	`"transaction"`
Пользователь вендора	`didit_internal_id`	`"vendor_user"`
Компания вендора	`didit_internal_id`	`"vendor_business"`

В системных списках блокировки Пользователь и Компании Didit также переводит соответствующих пользователей или компании в статус BLOCKED: тех, у которых vendor_data равен value, или тех, у которых didit_internal_id равен reference_object_uuid. См. Список блокировки пользователей и Список блокировки компаний.

Авторизации

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.

Параметры пути

list_uuid

string<uuid>

обязательно

UUID списка, в который нужно добавить запись. Если лицо есть только в виде изображения, используйте вместо этого Upload a face to a list.

Тело

application/json

Отправьте value, reference_session_id или оба параметра. Какие поля применимы, зависит от entry_type списка.

value

string

Значение для включения в список, проверяемое на соответствие параметру списка entry_type: для email: корректный адрес электронной почты; для phone: корректный международный номер, сохраняемый в формате E.164; для ip_address: IP-адрес или CIDR-диапазон (например, 10.0.0.0/8); для device_fingerprint: не менее 8 символов, состоящих из букв, цифр, -, _, : и . (список блокировки отклоняет отпечаток, о котором сообщили несколько различных устройств); для country: код ISO 3166-1 alpha-2 или alpha-3, сохраняемый как alpha-3; для user и business: значение vendor_data; для любого другого типа: непустая строка. Сохраняется в нижнем регистре, за исключением телефонных номеров и кодов стран, при этом список содержит каждое значение только один раз (без учёта регистра). Обязательно, если не передан reference_session_id; должно оставаться пустым при face_image_source с захватом документа.

reference_session_id

string<uuid>

Сессия верификации личности или компании вашего приложения, из которой берётся значение. Didit считывает самую последнюю запись сессии для указанного типа (face, document, phone, email, ip_address или device_fingerprint), связывает запись списка с сессией и этой записью, а также заполняет display_label и metadata для документов. Для списка блокировки типа device_fingerprint сессия, имеющая только отпечаток класса устройства или завершённая более чем на одном устройстве, отклоняется: передайте точный фингерпринт в качестве value. Для других типов записей или если в сессии нет такой записи, также передайте value; в этом случае ваше значение value сохраняется, а запись всё равно связывается с сессией.

reference_object_uuid

string<uuid>

UUID записи, которой соответствует элемент, если он получен не из сессии: UUID транзакции или didit_internal_id пользователя либо компании. Используйте в паре с metadata.reference_type. Заменяется записью сессии, если указан reference_session_id.

face_image_source

enum<string>

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

Списки лиц с reference_session_id: из какого изображения сессии взято лицо. liveness (по умолчанию) означает селфи проверки живости. front_image_camera_front и back_image_camera_front представляют собой селфи, сделанные фронтальной камерой во время фотографирования пользователем лицевой или обратной стороны документа: принимаются только в системном списке блокировки лиц, с reference_session_id и пустым value. Каждое селфи можно добавить один раз, и на нем должно быть четко видно одно лицо.

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

liveness,

front_image_camera_front,

back_image_camera_front

reference_node_id

string | null

При face_image_source из захвата документа: узел верификации личности, чьё селфи использовать (для сценариев с несколькими узлами). По умолчанию используется самая последняя верификация личности с этим изображением. Отклоняется при liveness.

Maximum string length: 100

display_label

string

Понятная метка. Если она пуста, Didit формирует её на основе сессии, где это возможно (например, имя владельца и номер документа).

Maximum string length: 512

comment

string

Примечание в виде произвольного текста, например причина включения в список.

metadata

object

JSON в свободной форме, сохраняемый с записью и возвращаемый в сохранённом виде. Используйте reference_type и reference_id, чтобы консоль ссылалась на первоисточник. Поля reference_image_url и front_image_url задаются только Didit и игнорируются при их отправке вами. Для записи, считанной из сессии, ключи Didit объединяются с вашими.

Show child attributes

Ответ

Запись была создана.

Одно значение в списке.

uuid

string<uuid>

обязательно

Идентификатор записи. Используйте его в качестве entry_uuid в запросе «Удалить запись списка».

value

string

обязательно

Значение из списка: номер телефона в формате E.164, адрес электронной почты, номер документа, IP-адрес или диапазон CIDR, цифровой отпечаток устройства, адрес кошелька, банковский счёт, трёхбуквенный код страны по стандарту ISO 3166-1 alpha-3, vendor_data, любая строка в списке типа key или UUID сохранённого лица в списке лиц. Отправляемые вами значения сохраняются в нижнем регистре, за исключением номеров телефонов и кодов стран. Сопоставление нечувствительно к регистру.

display_label

string | null

обязательно

Понятная метка. Didit заполняет её для записей, взятых из сессии (например, имя владельца и номер документа), если вы ничего не передали.

Maximum string length: 512

comment

string

обязательно

Примечание в виде произвольного текста. Пустая строка, если не задано.

added_by

string | null

обязательно

Кто добавил запись: api (API-ключ), адрес электронной почты пользователя консоли или console, system или migration (записи, созданные Didit), либо rule (действие правила транзакций или мониторинга).

reference_session_id

string<uuid> | null

обязательно

Сессия верификации, из которой была взята запись. null, если запись была добавлена по значению.

reference_session_number

integer | null

обязательно

Номер этой сессии в рамках приложения, как он отображается в консоли.

reference_session_type

enum<string> | null

обязательно

kyc для сессии проверки физического лица, kyb для сессии верификации бизнеса, null, если сессия отсутствует.

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

kyc,

kyb,

null

reference_object_uuid

string<uuid> | null

обязательно

Запись, которой соответствует элемент: запись лица, документа, телефона или адреса электронной почты, считанная из сессии, лицо, созданное с помощью «Загрузить лицо в список», или переданный вами UUID (например, UUID транзакции или didit_internal_id пользователя).

metadata

object | null

обязательно

Дополнительный контекст. Содержит ключи, установленные Didit (перечисленные здесь), объединенные с любыми metadata, переданными вами при создании записи, и возвращается в сохраненном виде. null, если контекст отсутствует.

Show child attributes

created_at

string<date-time>

обязательно

Когда запись была добавлена.

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

​Добавление из сессии

​Лица из селфи при съёмке документа

​Сессии с несколькими записями одного типа

​Ссылки на транзакции, пользователей и компании

Авторизации

Параметры пути

Тело

Ответ

Добавление из сессии

Лица из селфи при съёмке документа

Сессии с несколькими записями одного типа

Ссылки на транзакции, пользователей и компании