> ## 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: 전달 가능성 및 유출 신호

> OTP를 보내지 않고 이메일 주소의 위험 점수를 산정하세요. 전달 가능성, 일회용 도메인, 유출, 사기 신호를 서버 간 단일 호출로 제공하는 Didit API입니다.

Email Risk API 요청은 `POST /v3/email/risk/`를 사용하세요. 사용자에게 일회용 코드를 입력하도록 요구하지 않고도 이메일 인텔리전스를 얻을 수 있습니다.

이 API는 이메일을 보내지 않습니다. API 세션을 생성하고, 주소를 보강하며, 귀사의 이메일 위험 규칙을 적용합니다. 그리고 하나의 동기식 응답으로 이메일 인증에서 사용하는 것과 같은 정규화된 이메일 블록을 반환합니다.

요청이 저장되면 Didit은 점수가 매겨진 이메일을 **Networks**에서 집계 증거로도 사용할 수 있습니다. 네트워크 그래프에는 공유된 이메일 신호에 대한 고위험 이메일 인텔리전스, 유출 정보 맥락, 소셜 프로필 커버리지가 표시될 수 있습니다. 다만 다른 조직에 원본 이메일 주소를 노출하지는 않습니다.

## 응답 해석

* `status`는 이 API 세션의 최종 결정입니다. 보통 `Approved`이며, 위험 평가에서는 `In Review` 또는 `Declined`가 나올 수 있습니다.
* `email.is_breached`, `email.is_disposable`, `email.is_undeliverable`은 애플리케이션 로직에서 사용할 수 있는 안정적인 예/아니요 신호입니다.
* `email.breaches`는 적용 범위가 있을 때 해당 주소가 포함된 가장 최근의 알려진 유출 내역을 유출 날짜와 노출된 데이터 유형과 함께 나열합니다.
* `email.email_intelligence.score`는 0\~100 위험 척도를 사용하며, 숫자가 높을수록 위험이 큽니다. `breach_risk_level`(`Low`, `Medium`, `High`)과 `no_of_breaches`는 파생된 값입니다.
* `email.email_intelligence.reason_codes`는 어떤 정규화된 신호가 결과에 기여했는지 설명합니다. 값은 시간이 지나면서 늘어날 수 있으므로 알 수 없는 코드를 거부하지 마세요.
* `email.email_intelligence`와 `email.enrichment`는 같은 정규화된 객체를 가리키는 호환성 별칭입니다. 새로운 연동에서는 `email.enrichment`를 읽으면 됩니다.
* `email.matches`는 같은 주소가 다른 사용자에 의해 사용된 애플리케이션의 다른 세션을 나열합니다. 중복 계정 탐지에 사용하세요.
* `request_id`는 API 세션 ID입니다. 나중의 webhook이나 콘솔 활동과 결과를 연관시켜야 한다면 `vendor_data`와 함께 저장하세요.

> [!WARNING]
>
> `email.email_intelligence`와 `email.enrichment`는 최선의 노력으로 제공되는 필드입니다. 해당 주소, 도메인 또는 요금제에 대해 사용 가능한 인텔리전스 데이터가 반환되지 않으면, 조회가 완료되더라도 두 필드가 모두 생략될 수 있습니다. 규칙은 먼저 `is_breached`, `is_disposable`, `is_undeliverable`을 기준으로 작성하고, 인텔리전스 데이터가 없는 경우를 "안전함"이 아니라 "알 수 없음"으로 처리하세요.

## 소셜 발자국 부가 기능

`enable_social`을 `true`로 설정하면 응답의 `email` 아래에 `email_social` 블록이 추가됩니다. 이 블록에는 이메일 주소가 등록된 온라인 플랫폼이 카테고리별로 묶여 있고, 요약 개수와 데이터 파트너가 반환하는 프로필 세부 정보가 함께 포함됩니다.

* `email.email_social.profiles_registered`와 `email.email_social.profiles_checked`는 핵심 수치입니다. 평가된 플랫폼 중 이메일 주소가 등록된 것으로 확인된 플랫폼의 수를 나타냅니다.
* `email.email_social.registered_platforms`와 `email.email_social.not_registered_platforms`는 각 플랫폼을 `category`와 `scope`(`global`, 또는 지역별 플랫폼의 경우 `local`)와 함께 나열합니다.
* `email.email_social.categories`는 카테고리별 등록 개수와 비율을 제공합니다. `email.email_social.profiles`는 플랫폼이 정보를 공개하는 경우 플랫폼별 프로필 세부 정보(이름, 사진 URL, 소개 텍스트, 개인정보 보호 상태, 비즈니스 계정 여부)를 포함합니다.
* 요약 지표(`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`)는 0\~10 복합 점수입니다. 확인 과정에서 데이터가 반환되지 않은 개수는 모두 `null`일 수 있습니다.

`profiles_registered: 0`은 실패가 아니라 실제 결과입니다. 플랫폼을 확인했고 이메일 주소가 어디에도 없었다는 뜻이며, 이는 흔한 합성 신원 신호입니다. 이 엔드포인트는 이 값만으로 조치를 취하지 않습니다. 이를 검토 또는 거부 판정으로 바꾸려면 워크플로에서 `email_no_social_presence_action`을 사용하세요.

`enable_social`을 설정하지 않으면 블록이 없습니다. 소셜 확인을 완료하지 못한 경우에도 블록이 없으며, 이때는 과금되지 않습니다.

## 샌드박스 동작

샌드박스 키는 요청을 검증하고 항상 동일한 승인 데이터를 반환합니다. 이메일을 보내지 않고, 크레딧을 소모하지 않으며, 세션을 생성하지 않고, **Networks**에 기여하지도 않습니다. `enable_social`을 설정하면 항상 동일한 `email_social` 블록도 함께 반환합니다.

## 결제

Email Risk API 호출은 정가 기준 \$0.04입니다. 이메일을 보내지 않기 때문에 전체 이메일 인증보다 비용이 낮습니다. 실제 요청은 조회가 시작되는 시점부터 과금되며, 최선 노력 필드 일부를 사용할 수 없더라도 마찬가지입니다.

소셜 발자국 부가 기능은 별도로 과금됩니다. 요청당 Email Risk API 가격에 더해 `email_social` 단위 1개가 부과되며, 확인이 완료될 때마다 적용됩니다. 조회 전에 수행되는 크레딧 확인은 두 항목을 모두 포함합니다.


## OpenAPI

````yaml ko/openapi-25.json POST /v3/email/risk/
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/email/risk/:
    post:
      tags:
        - Standalone APIs
      summary: 이메일 주소 위험 점수 산정
      description: >-
        OTP를 전송하지 않고 전송 가능 여부, 일회용 주소 여부, 유출 이력, 세션 간 일치 여부 및 정규화된 위험 인텔리전스 신호를
        반환합니다. 이 endpoint는 API 세션을 생성하고 해당 ID를 `request_id`로 반환합니다.


        **결정.** 최상위 `status`는 `email.status`를 그대로 반영합니다. 일반적으로 `Approved`이며, 위험
        평가에 따라 `In Review` 또는 `Declined`가 될 수 있습니다.


        **호환성 별칭.** 프로덕션 응답은 정규화된 인텔리전스 객체를 `email.email_intelligence`와
        `email.enrichment` 둘 다로 제공합니다. 두 값은 동일합니다. 새로운 연동에서는 `email.enrichment`를
        읽으시면 됩니다. 사용 가능한 인텔리전스 데이터가 반환되지 않은 경우 두 키 모두 생략됩니다.


        **결제.** 프로덕션 호출에는 Email Risk API 요금이 적용됩니다. 조회가 시작되면 최선 노력(best-effort)
        방식으로 제공되는 일부 필드를 사용할 수 없더라도 요청에 대한 요금이 청구됩니다.


        **샌드박스.** 샌드박스 키는 이메일을 전송하거나 크레딧을 소비하거나 세션을 생성하거나 Networks에 기여하지 않고, 요청을
        검증한 후 결정론적인 승인 데이터를 반환합니다.


        **인증.** 애플리케이션의 API 키를 `x-api-key`에 넣어 전송하십시오. 인증 정보가 누락되었거나 유효하지 않은 경우
        `403`을 반환하며, 이 API는 `401`을 절대 반환하지 않습니다.


        **속도 제한.** POST/PATCH/DELETE endpoint 전반에 걸쳐 API 키당 분당 300개의 쓰기 요청 예산이
        공유됩니다(거래 생성 및 이벤트 수집은 별도로 600개의 예산이 배정됨).


        **소셜 발자국.** `enable_social`을 `true`로 설정하면 `email_social` 블록이 추가됩니다. 여기에는
        카테고리별 개수 및 확인 가능한 프로필 세부 정보와 함께 이 주소가 등록된 온라인 플랫폼 목록이 포함됩니다.
        `profiles_registered: 0`은 플랫폼들을 확인했으나 해당 주소가 어느 곳에서도 발견되지 않았음을 의미하며,
        유효하고 청구 가능한 응답입니다. 부가 기능을 요청하지 않았거나 확인을 완료할 수 없는 경우 해당 블록은 생략되며, 이 경우
        요금이 청구되지 않습니다. 결제 시 이 endpoint 자체의 가격에 더해 요청당 1건의 `email_social` 단위가 추가
        청구됩니다.
      operationId: post_v3email_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRiskRequest'
            examples:
              Minimal:
                summary: 기본값으로 주소 점수 산정
                value:
                  email: alice@example.com
              Full context:
                summary: 신호, 국가 힌트 및 상관관계 ID를 포함한 점수 산정
                value:
                  email: alice@example.com
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: web
                    os_version: '14.4'
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4
                      Safari/605.1.15
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            위험 평가가 완료되었습니다. 결정 사항은 `status`를 확인하십시오. 완료된 조회의 경우 HTTP는 항상
            `200`입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRiskResponse'
              examples:
                Clean address:
                  summary: 유출 위험이 없는 전송 가능한 주소
                  value:
                    request_id: 82397be9-5921-4970-a979-2d5b43e08b33
                    status: Approved
                    email:
                      status: Approved
                      email: alice@example.com
                      is_breached: false
                      breaches: []
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                      enrichment:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Breached address:
                  summary: 알려진 데이터 유출 사건에서 발견된 주소
                  value:
                    request_id: d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d
                    status: In Review
                    email:
                      status: In Review
                      email: bob@example.org
                      is_breached: true
                      breaches:
                        - name: ExampleBreach2023
                          domain: example.org
                          breach_date: '2023-06-01'
                          breach_emails_count: 1200000
                          description: A data breach affecting example.org accounts.
                          logo_path: https://logos.example.org/example.png
                          data_classes:
                            - email_addresses
                            - passwords
                          is_verified: true
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                      enrichment:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                    vendor_data: lead-125
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/EmailRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/email/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "alice@example.com",
                "country_code": "US",
                "vendor_data": "lead-123",
                "metadata": {"source": "signup_prescreen"}
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.email.assess_risk(
                email="alice@example.com",
            )
            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.email.assessRisk({
              email: "alice@example.com",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\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.EmailRiskRequest;

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

            var result = client.email().assessRisk(EmailRiskRequest.builder()
                    .email("alice@example.com")
                    .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->email->assessRisk([
                'email' => 'alice@example.com',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.email.assess_risk(email: "alice@example.com")
            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.Email.AssessRiskAsync(new EmailRiskRequest
            {
                Email = "alice@example.com",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    EmailRiskRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: 점수를 산정할 이메일 주소입니다.
          example: alice@example.com
        country_code:
          type: string
          maxLength: 3
          description: 인텔리전스 적용 범위를 위한 선택적 ISO 3166-1 alpha-2 또는 alpha-3 국가 힌트입니다.
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: 이 요청에 대한 안정적인 참조값입니다. API 세션에 저장되며 응답에 그대로 반영됩니다.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 귀하의 비민감 JSON 메타데이터입니다. API 세션에 저장되며 응답에 그대로 반환됩니다.
        enable_social:
          type: boolean
          default: false
          description: >-
            true인 경우, 주소의 소셜 발자국(등록된 이메일, 소셜, 전문, 전자상거래 및 엔터테인먼트 플랫폼)도 조회합니다. 이
            endpoint 자체의 가격 외에 요청당 `email_social` 1단위로 청구됩니다.
          example: true
    EmailRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            이 요청에 대해 생성된 API 세션의 ID입니다. 결과를 향후의 webhook이나 콘솔 활동과 연결해야 하는 경우
            `vendor_data`와 함께 저장하세요.
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: >-
            이 API 세션의 최종 결정입니다. 일반적으로 `Approved`이며, 위험 평가에 따라 `In Review` 또는
            `Declined`가 생성될 수 있습니다.
        vendor_data:
          type: string
          nullable: true
          description: 전송한 `vendor_data`의 에코 값이며, 전송하지 않은 경우 `null`입니다.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 전송한 `metadata`의 에코 값이며, 전송하지 않은 경우 `null`입니다.
        created_at:
          type: string
          format: date-time
          description: 이 응답의 타임스탬프입니다.
        email:
          type: object
          description: 이메일 인증 응답에서 사용되는 것과 동일한 블록인 정규화된 이메일 보고서입니다.
          required:
            - status
            - email
            - is_breached
            - breaches
            - is_disposable
            - is_undeliverable
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: 이 이메일 주소에 대한 결정입니다. 최상위 `status`를 반영합니다.
            email:
              type: string
              description: 점수가 산정된 주소입니다.
              example: alice@example.com
            is_breached:
              type: boolean
              description: 주소가 알려진 자격 증명 유출에 나타나는지 여부입니다.
            breaches:
              type: array
              description: >-
                이 주소를 포함하는 가장 최근의 알려진 침해 사례 최대 5건입니다. `is_breached`가 `false`이면 빈
                배열입니다.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: 침해 식별자입니다.
                  domain:
                    type: string
                    description: 침해된 서비스의 도메인입니다.
                  breach_date:
                    type: string
                    format: date
                    description: 위반이 발생한 일자입니다.
                  breach_emails_count:
                    type: integer
                    description: 유출 사건에서 노출된 계정의 총 개수입니다.
                  description:
                    type: string
                    description: 침해에 대한 사람이 읽기 쉬운 설명입니다(HTML 마크업을 포함할 수 있음).
                  logo_path:
                    type: string
                    description: 침해된 서비스 로고의 URL입니다.
                  data_classes:
                    type: array
                    items:
                      type: string
                    description: >-
                      노출된 데이터의 카테고리(snake_case 형식, 예: `email_addresses`,
                      `passwords`).
                  is_verified:
                    type: boolean
                    description: 유출이 사실인 것으로 확인되었는지 여부입니다.
            is_disposable:
              type: boolean
              description: 도메인이 일회용 제공업체에 속하는지 여부입니다.
            is_undeliverable:
              type: boolean
              description: 주소로 전송할 수 없는 것으로 확인되었는지 여부입니다.
            verification_attempts:
              type: integer
              description: 이 주소에 대한 OTP 전송 횟수입니다. 위험 조회의 경우 `0`입니다.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: 주소가 OTP를 통해 마지막으로 인증된 시점입니다. 위험 조회의 경우 `null`입니다.
            warnings:
              type: array
              description: 이 요청에 대해 기록된 위험 경고. 없을 경우 빈 배열입니다.
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: 요청의 시간순 감사 로그입니다. 전송이 없는 위험 조회의 경우 빈 배열입니다.
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: >-
                다른 사용자(다른 `vendor_data`)가 동일한 이메일 주소를 사용한 애플리케이션의 다른 세션입니다. 최대
                5개 항목입니다. 일치하는 항목이 없으면 빈 배열입니다.
              items:
                $ref: '#/components/schemas/EmailMatchItem'
            email_intelligence:
              $ref: '#/components/schemas/EmailIntelligence'
            enrichment:
              $ref: '#/components/schemas/EmailIntelligence'
            email_social:
              $ref: '#/components/schemas/EmailSocialFootprint'
    RiskSignals:
      type: object
      description: >-
        애플리케이션에서 관찰한 선택적 기기 및 네트워크 컨텍스트입니다. 모든 필드는 선택 사항입니다. 이를 전달하면 Networks의
        세션 간 일치 감지 기능에 데이터가 제공됩니다.
      properties:
        ip:
          type: string
          format: ip
          description: 최종 사용자에 대해 관찰된 IPv4 또는 IPv6 주소입니다.
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: >-
            애플리케이션에서 수집한 안정적인 기기 식별자(Android `ANDROID_ID`, iOS
            `identifierForVendor`)입니다.
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: 최종 사용자 기기의 플랫폼입니다.
        device_model:
          type: string
          maxLength: 255
          description: 애플리케이션에서 보고한 기기 모델입니다.
        os_version:
          type: string
          maxLength: 64
          description: 운영체제 버전입니다.
        app_version:
          type: string
          maxLength: 64
          description: 애플리케이션의 버전입니다.
        user_agent:
          type: string
          maxLength: 512
          description: 브라우저 또는 앱 사용자 에이전트입니다.
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: 경고를 생성한 기능입니다.
        risk:
          type: string
          description: 기계 판독 가능한 위험 코드입니다. 향후 새로운 값이 추가될 수 있습니다.
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: 위험별 컨텍스트 또는 `null`.
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: 결정 규칙에서 사용하는 심각도입니다.
        short_description:
          type: string
          description: 사람이 읽을 수 있는 한 줄 요약입니다.
        long_description:
          type: string
          description: 사람이 읽기 쉬운 설명입니다.
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: 기계 판독 가능한 이벤트 유형. 시간이 지남에 따라 새로운 값이 추가될 수 있습니다.
        timestamp:
          type: string
          format: date-time
          description: 이벤트가 발생한 시점입니다.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: 이벤트 관련 payload 또는 `null`입니다.
        fee:
          type: number
          description: 이 이벤트에 대해 청구된 USD 금액입니다.
    EmailMatchItem:
      type: object
      description: 동일한 이메일 주소를 다른 `vendor_data`와 함께 사용한 애플리케이션의 다른 세션입니다.
      properties:
        session_id:
          type: string
          format: uuid
          description: 이 이메일 주소를 사용한 다른 인증의 세션 id입니다.
        session_number:
          type: integer
          description: 해당 세션의 사람이 읽기 쉬운 순차 번호입니다.
        vendor_data:
          type: string
          nullable: true
          description: 해당 세션의 `vendor_data`입니다.
        verification_date:
          type: string
          description: 해당 세션이 생성된 시점(`YYYY-MM-DDTHH:MM:SSZ`)입니다.
        email:
          type: string
          description: 일치하는 이메일 주소입니다.
        status:
          type: string
          description: '해당 세션의 상태(예: `Approved`, `Declined`, `In Progress`)입니다.'
        is_blocklisted:
          type: boolean
          description: 이메일 주소가 애플리케이션의 차단 목록에 있는지 여부입니다.
        api_service:
          type: string
          nullable: true
          description: API 유형 세션의 경우 이를 생성한 독립형 API, 일반 인증 세션의 경우 `null`입니다.
        source:
          type: string
          description: >-
            일치 항목이 발견된 위치입니다. 일반적으로 `session`이며, 조직 목록 항목을 통한 차단 목록 일치는
            `list_entry`를 사용합니다.
    EmailIntelligence:
      type: object
      description: >-
        정규화된 이메일 인텔리전스 블록입니다. 이 이메일에 대해 인텔리전스 애드온이 실행된 경우에만 존재하며, 존재하는 경우 동일한 값을
        가진 `enrichment` 별칭으로도 노출됩니다.
      properties:
        score:
          type: number
          nullable: true
          description: 정규화된 0-100 위험 점수입니다. 높을수록 위험합니다.
        deliverable:
          type: string
          nullable: true
          description: '전송 가능성 구간(예: `high`).'
        breach_risk_level:
          type: string
          nullable: true
          description: '`Low`, `Medium` 또는 `High`.'
        breach_risk_index:
          type: number
          nullable: true
          description: 숫자 침해 위험 지수입니다.
        is_recent_breach:
          type: boolean
          nullable: true
          description: 주소가 최근 유출 사고에 나타난 경우 `true`입니다.
        is_frequent_breached:
          type: boolean
          nullable: true
          description: 주소가 다수의 유출 사고에 나타난 경우 `true`입니다.
        is_disposable:
          type: boolean
          nullable: true
          description: 도메인이 일회용 이메일 제공업체인 경우 `true`입니다.
        is_free_domain:
          type: boolean
          nullable: true
          description: 도메인이 무료 메일 제공업체인 경우 `true`입니다.
        is_breached:
          type: boolean
          nullable: true
          description: 주소가 알려진 유출 사고에 나타난 경우 `true`입니다.
        no_of_breaches:
          type: number
          nullable: true
          description: 해당 주소가 포함된 알려진 유출 건수입니다.
        reason_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  신호의 안정적인 Didit 식별자입니다(예: `IR-5AC67A32`). 불투명한 값이므로 구문 분석하지 말고
                  그룹화 및 필터링에만 사용하세요.
              value:
                nullable: true
                description: >-
                  위험 플래그(예: `voip`, `leaked`, `disposable`, `spam_trap`)의 경우 해당
                  값: boolean, 수준 또는 날짜입니다. 점수가 산정된 사유 코드의 경우 null입니다.
              direction:
                type: string
                enum:
                  - risk
                  - trust
                description: 신호가 위험을 높였는지 또는 신뢰도를 높였는지 여부입니다.
              message:
                type: string
                description: 신호에 대한 사람이 읽기 쉬운 영어 설명입니다.
              impact_level:
                type: string
                nullable: true
                description: >-
                  시그널이 점수를 얼마나 크게 변동시켰는지 나타내며, 예를 들어 `low`, `medium`, `high` 등이
                  있습니다.
          description: >-
            점수를 설명하는 신호 목록으로, 각각 안정적인 Didit 코드, 방향, 메시지 및 영향 수준을 포함합니다. 새로운 코드가
            점진적으로 추가될 수 있으므로 알 수 없는 코드를 거부하지 마세요.
    EmailSocialFootprint:
      type: object
      nullable: true
      description: >-
        이메일 주소의 소셜 풋프린트(등록된 온라인 플랫폼)입니다. `enable_social`이 설정되고 확인이 완료된 경우에만
        표시됩니다. 반환된 데이터가 없는 경우 각 개수는 null일 수 있습니다. `profiles_registered: 0`은 플랫폼을
        확인했으나 해당 이메일 주소가 어떤 플랫폼에서도 발견되지 않았음을 의미하며, 이는 유효하고 요금이 청구되는 응답이자 흔히 나타나는
        합성 신원 신호입니다.
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: 이메일 주소 등록이 확인된 플랫폼입니다.
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: 가입 여부가 평가된 플랫폼입니다.
          example: 14
        names_found:
          type: integer
          nullable: true
          description: 관련 이름을 반환한 플랫폼입니다.
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: 프로필 사진을 반환한 플랫폼입니다.
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: 존재가 감지된 커뮤니케이션 플랫폼입니다.
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: 존재가 감지된 고유한 플랫폼 카테고리입니다.
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: 복합 디지털 성숙도 지표(0-10)입니다.
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: 프로필 정보량 지표, 0-10.
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: 무료 대 유료 플랫폼 비율(0-10)입니다.
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: 무료 플랫폼에서의 등록 수입니다.
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: 완전 유료 플랫폼에서의 등록 수입니다.
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: 프리미엄(freemium) 플랫폼에서의 등록 수입니다.
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: WhatsApp 프로필의 완성도입니다. 전화번호 전용이며 이메일의 경우 null입니다.
          example: Partial
        registered_platforms:
          type: array
          description: 가입이 확인된 플랫폼입니다.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: 부정적인 결과가 반환된 플랫폼입니다.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: 플랫폼 카테고리별 등록 수 및 비율입니다.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: 플랫폼에서 프로필 세부 정보를 제공하는 경우, 플랫폼을 키로 하는 플랫폼별 프로필 세부 정보입니다.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: 플랫폼 식별자입니다.
          example: whatsapp
        category:
          type: string
          description: >-
            플랫폼 카테고리(예: MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL,
            EMAIL_PROVIDER)입니다.
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: 글로벌 플랫폼의 경우 `global`, 특정 지역 플랫폼의 경우 `local`.
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: 이 카테고리에서 가입이 확인된 플랫폼입니다.
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: 해당 카테고리에서 확인된 플랫폼 중 등록이 있는 플랫폼의 비율(0.0-1.0)입니다.
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: 플랫폼에서 제공하는 경우 프로필 이름입니다.
        photo:
          type: string
          nullable: true
          description: 플랫폼에서 제공하는 경우 프로필 사진 URL입니다.
        about:
          type: string
          nullable: true
          description: 플랫폼에서 제공하는 경우 프로필 소개/약력 텍스트입니다.
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: 플랫폼에서 제공하는 경우 프로필 공개 여부입니다.
        business_account:
          type: boolean
          nullable: true
          description: 플랫폼에서 정보를 제공하는 경우, 프로필이 비즈니스 계정인지 여부입니다.
  responses:
    EmailRiskValidationError:
      description: 요청 유효성 검사에 실패했습니다.
      content:
        application/json:
          examples:
            Missing email:
              summary: 이메일이 누락되었습니다
              value:
                email:
                  - This field is required.
            Invalid email:
              summary: 유효하지 않은 이메일
              value:
                email:
                  - Enter a valid email address.
            Invalid country hint:
              summary: 유효하지 않은 국가 힌트
              value:
                country_code:
                  - Ensure this field has no more than 3 characters.
    RiskPermissionDenied:
      description: >-
        API 키가 누락되었거나 유효하지 않거나, 조직이 실시간 조회 비용을 충당할 수 없습니다. 이 API는 절대 `401`을 반환하지
        않습니다.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: '`x-api-key` 헤더가 없거나, 키가 유효하지 않거나 해지되었습니다'
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: 조직 잔액이 조회 가격을 충당할 수 없습니다
              value:
                error: You don't have enough credits to perform this request.
    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.