> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 차단 목록 추가 API: 세션 항목 차단

> POST /v3/blocklist/add/: Didit 인증 세션의 얼굴, 문서, 전화번호 또는 이메일을 차단 목록에 추가해 일치하는 새 세션을 거부합니다.

세션에서 수집한 얼굴, 신분증, 전화번호 또는 이메일 주소를 차단 목록에 추가합니다. Didit은 선택한 각 레코드를 차단됨으로 표시하고, 해당 유형의 시스템 차단 목록에 세션과 연결하여 추가합니다. 이후 일치하는 얼굴, 문서 번호, 전화번호 또는 이메일 주소를 가진 새 세션은 거부됩니다.

차단 목록 추가 API 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\`Blocklist the face, document, phone number or email address of one of my Didit verification sessions through the Management API.

Endpoint:
POST https://verification.didit.me/v3/blocklist/add/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- After reviewing a fraudulent session, block what it collected so the same person is declined next time.

Request body (application/json):
\{
"session_id": "33333333-4444-5555-6666-777777777777", // required: a verification session of my application
"blocklist_face": true,       // optional, default false
"blocklist_document": true,   // optional, default false
"blocklist_phone": false,     // optional, default false
"blocklist_email": false      // optional, default false
}
At least one blocklist_* flag must be true.

Behavior:
\- Didit uses the session's most recent record of each selected type.
\- Each selected record is flagged as blocklisted and gets an entry, linked to the session, in the matching system blocklist (added_by "api").
\- From then on, new sessions with a matching face, document number, phone number or email address are declined.
\- The session itself and sessions that already finished are not changed.
\- Safe to repeat: an item already listed keeps its single entry, and its blocklisted_at is refreshed.
\- All or nothing: Didit checks every selected item first. If one is missing, nothing is blocklisted.
\- A document needs its issuing state, document type, document number and full name.

Example call:
curl -X POST "https://verification.didit.me/v3/blocklist/add/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true}'

Example response (200):
\{ "message": "Successfully updated blocklist." }

Failure modes:
\- 400: session_id is missing ({ "session_id": ["This field is required."] }) or not a UUID ({ "session_id": ["Must be a valid UUID."] }); the session is not a verification session of this application ({ "non_field_errors": ["Session not found"] }; business verification sessions are not accepted); no flag is true ({ "non_field_errors": ["Must specify at least one item to blocklist"] }); the session has no record of a selected type ({ "non_field_errors": ["Session does not have a face record"] }); or the document lacks a required field.
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- Writes entries to the system face, document, phone and email blocklists and blocks matching new sessions.

To block a value without a session, or an IP address, device fingerprint, user or business, use POST /v3/lists/{list_uuid}/entries/ on the matching system blocklist instead.

For the full integration shape, see /integration/integration-prompt.`

\</pre>



      
      

붙여넣을 곳

> [!NOTE]
>
> 이 호출은 전부 성공하거나 전부 실패합니다. 세션에 선택한 유형의 레코드가 없거나, 문서에 발급 국가, 문서 유형, 문서 번호 또는 성명이 없으면 `400`을 반환하며 어떤 항목도 차단되지 않습니다. 이미 차단된 항목에 대해 호출을 반복해도 안전합니다.차단된 항목을 확인하려면 [차단 목록 항목 조회](https://docs.didit.me/ko/management-api/blocklist/list.md)를 사용하십시오. 차단을 해제하려면 [차단 목록에서 제거](https://docs.didit.me/ko/management-api/blocklist/remove.md)를 사용하십시오. 주소, 기기 지문, 사용자, 기업 또는 세션이 없는 값을 차단하려면 [항목 생성](https://docs.didit.me/ko/management-api/lists/create-entry.md)으로 해당 시스템 차단 목록에 항목을 추가하십시오. 차단 목록이 적용되는 방식은 [사용자 차단 목록](https://docs.didit.me/ko/entities/users/blocklist.md)을 참조하십시오.


## OpenAPI

````yaml ko/openapi-25.json POST /v3/blocklist/add/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/blocklist/add/:
    post:
      tags:
        - Blocklist
      summary: 세션 항목을 차단 목록에 추가
      description: >-
        애플리케이션의 단일 개인 인증 세션에 사용된 얼굴, 신분증 문서, 전화번호 또는 이메일 주소를 차단 목록에 추가합니다. 선택한 각
        유형에 대해 Didit은 세션의 가장 최신 기록을 가져와 차단 목록에 등록된 것으로 표시하고 세션에 연결된 항목을 일치하는 시스템
        차단 목록(`added_by: "api"`)에 추가합니다. 이에 따라 일치하는 얼굴, 문서 번호, 전화번호 또는 이메일 주소를
        가진 새 세션은 거부됩니다. 선택한 모든 항목을 먼저 검사하므로 하나라도 누락되면 아무것도 차단 목록에 추가되지 않습니다. 이미
        등록된 항목에 대해 호출을 반복하면 단일 항목이 유지되고 `blocklisted_at`이 갱신됩니다. 해당 세션 자체와 이미
        완료된 세션은 변경되지 않습니다. 범위가 지정된 API 키에는 `workflows: write` 권한이 필요합니다.
      operationId: add_to_blocklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - session_id
              description: 최소 하나의 `blocklist_*` 플래그가 `true`여야 합니다.
              properties:
                session_id:
                  type: string
                  format: uuid
                  description: 애플리케이션의 사용자 인증 세션입니다. 삭제된 세션은 거부됩니다.
                blocklist_face:
                  type: boolean
                  default: false
                  description: 세션의 얼굴을 차단 목록에 추가합니다.
                blocklist_document:
                  type: boolean
                  default: false
                  description: >-
                    세션의 신분증 문서를 차단 목록에 추가합니다. 문서에는 발급 국가, 문서 유형, 문서 번호, 성명이
                    필요합니다.
                blocklist_phone:
                  type: boolean
                  default: false
                  description: 세션의 전화번호를 차단 목록에 추가합니다.
                blocklist_email:
                  type: boolean
                  default: false
                  description: 세션의 이메일 주소를 차단 목록에 추가합니다.
            examples:
              Face and document:
                value:
                  session_id: 33333333-4444-5555-6666-777777777777
                  blocklist_face: true
                  blocklist_document: true
              Phone only:
                value:
                  session_id: 33333333-4444-5555-6666-777777777777
                  blocklist_phone: true
      responses:
        '200':
          description: 선택한 항목이 차단 목록에 추가되었습니다.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: 항상 `Successfully updated blocklist.`입니다.
              examples:
                Blocklisted:
                  value:
                    message: Successfully updated blocklist.
        '400':
          description: >-
            본문이 잘못되었거나, 세션이 이 애플리케이션의 인증 세션이 아니거나, 선택한 유형의 기록이 없습니다. 아무것도 차단 목록에
            추가되지 않았습니다.
          content:
            application/json:
              examples:
                Unknown session:
                  value:
                    non_field_errors:
                      - Session not found
                No item selected:
                  value:
                    non_field_errors:
                      - Must specify at least one item to blocklist
                No face record:
                  value:
                    non_field_errors:
                      - Session does not have a face record
                Incomplete document:
                  value:
                    non_field_errors:
                      - >-
                        To blocklist a document, the document must have an
                        issuing state, document type, document number and full
                        name
                Invalid session id:
                  value:
                    session_id:
                      - Must be a valid UUID.
                Missing session id:
                  value:
                    session_id:
                      - This field is required.
        '401':
          description: 스코프가 지정된 API 키가 만료되었습니다. 기타 인증 실패 시에는 `403`이 반환됩니다.
          content:
            application/json:
              examples:
                Expired API key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            `x-api-key` 헤더가 누락되었거나(잘못되었거나 해지되었거나 만료된 키는 `401` 반환), 범위가 지정된 API
            키에 `workflows: write` 권한이 없거나 허용 목록 외부의 IP 주소에서 사용되었습니다.
          content:
            application/json:
              examples:
                Missing or invalid API key:
                  value:
                    detail: You do not have permission to perform this action.
                Scoped key without workflows access:
                  value:
                    detail: This API key has no write access to workflows.
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/blocklist/add/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "session_id": "33333333-4444-5555-6666-777777777777",
                "blocklist_face": true,
                "blocklist_document": true
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.blocklist.add(
                session_id="33333333-4444-5555-6666-777777777777",
                blocklist_face=True,
                blocklist_document=True,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

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

            const result = await didit.blocklist.add({
              session_id: "33333333-4444-5555-6666-777777777777",
              blocklist_face: true,
              blocklist_document: true,
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Add(ctx, didit.BlocklistAddParams{\n\tSessionID:         \"33333333-4444-5555-6666-777777777777\",\n\tBlocklistFace:     didit.Bool(true),\n\tBlocklistDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.BlocklistAddParams;

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

            var result = client.blocklist().add(BlocklistAddParams.builder()
                    .sessionId("33333333-4444-5555-6666-777777777777")
                    .blocklistFace(true)
                    .blocklistDocument(true)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

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

            $result = $didit->blocklist->add([
                'session_id' => '33333333-4444-5555-6666-777777777777',
                'blocklist_face' => true,
                'blocklist_document' => true,
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.blocklist.add(
              session_id: "33333333-4444-5555-6666-777777777777",
              blocklist_face: true,
              blocklist_document: true
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

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

            var result = await client.Blocklist.AddAsync(new BlocklistAddParams
            {
                SessionId = "33333333-4444-5555-6666-777777777777",
                BlocklistFace = true,
                BlocklistDocument = true,
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  responses:
    RateLimitedWrite:
      description: >-
        API 키당 분당 300개의 요청을 처리하는 공유 쓰기 속도 제한을 초과했습니다. 다시 시도하기 전에 `Retry-After`를
        준수하십시오.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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 를 참고하십시오.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.