리스트 항목 생성 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 알파-3 국가 코드(예: USA, GBR, ESP). 알파-2 코드(예: US)도 허용되며 알파-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)에 연결합니다.

시스템 얼굴, 문서, 전화번호, 이메일 차단 목록에서는 레코드도 차단됨으로 표시되어, 일치하는 새 세션이 거부됩니다. 그 밖의 항목 유형에서는 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가 저장되지만, 여전히 가장 최근 레코드에 연결되며, 시스템 차단 목록에서는 그 레코드가 차단됨으로 표시됩니다. 이전 레코드의 값을 목록에 추가하려면 reference_session_id 없이 value만 사용해 추가하십시오:

{
  "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은 자체 키를 사용자의 키에 추가하며, 키가 겹치면 Didit의 키가 우선합니다.

소스 엔터티	`reference_object_uuid`	`metadata.reference_type`
인증 세션	Didit이 설정(얼굴, 문서, 전화번호 또는 이메일 레코드)	필요 없음: `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

필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 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는 alpha-3로 저장되는 ISO 3166-1 alpha-2 또는 alpha-3 코드, user 및 business는 vendor_data, 기타 유형은 비어 있지 않은 문자열입니다. 전화번호와 국가 코드를 제외하고 소문자로 저장되며, 목록에는 각 값이 한 번만 포함됩니다(대소문자 구분 없음). reference_session_id가 전송되지 않는 한 필수이며, 문서 캡처 face_image_source를 사용하는 경우 비워 두어야 합니다.

reference_session_id

string<uuid>

값을 가져올 애플리케이션의 개인 또는 기업 확인(KYB) 세션입니다. 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

응답

항목이 생성되었습니다.

목록 내의 값 1개입니다.

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

필수

추가 컨텍스트입니다. 항목 생성 시 전송한 metadata와 병합된 Didit이 설정한 키(여기에 나열됨)가 포함되며, 저장된 그대로 반환됩니다. 없는 경우 null입니다.

Show child attributes

created_at

string<date-time>

필수

항목이 추가된 시점입니다.

마지막 수정일 2026년 11월 7일

​세션에서 추가하기

​문서 촬영 셀피의 얼굴

​같은 유형의 레코드가 여러 개인 세션

​거래, 사용자, 기업 참조하기

인증

경로 매개변수

본문

응답

세션에서 추가하기

문서 촬영 셀피의 얼굴

같은 유형의 레코드가 여러 개인 세션

거래, 사용자, 기업 참조하기