> ## 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: 통신사 및 사기 감지 신호

> Didit을 통해 OTP 발송 없이 전화번호의 위험 점수를 산정하세요. 단 한 번의 서버 간 호출로 통신사, 회선 유형, 번호 이동 및 사기 신호를 평가합니다.

OTP 흐름 이전, 이를 대신하거나 해당 흐름 외부에서 전화번호 인텔리전스가 필요한 경우 `POST /v3/phone/risk/`를 사용합니다.

사용자에게 코드를 전송하지 않습니다. API 세션을 생성하고, 번호 정보를 강화하며, 설정된 전화번호 위험 규칙을 적용한 뒤 전화번호 인증에서 사용되는 것과 동일한 정규화된 전화번호 블록을 단일 동기 응답으로 반환합니다.

요청이 저장되면 Didit은 점수가 매겨진 전화번호를 **네트워크**에서 집계된 증거로 활용할 수도 있습니다. 네트워크 그래프에는 공유된 전화 신호에 대한 고위험 전화번호 인텔리전스, 번호 이동 및 회선 유형 컨텍스트가 표시될 수 있지만, 원본 전화번호가 다른 조직에 공개되지는 않습니다.

## 응답 해석

* `status`는 이 API 세션에 대한 최종 결정입니다. 일반적으로 `Approved`이며, 위험 평가에 따라 `In Review` 또는 `Declined`가 될 수 있습니다.
* `phone.full_number`는 정규화된 E.164 형식의 번호입니다. `phone.phone_number_prefix` 및 `phone.phone_number`는 이를 국가 번호 접두사와 국내 번호로 분할합니다.
* `phone.is_disposable` 및 `phone.is_virtual`은 애플리케이션 로직을 위한 안정적인 예/아니오 신호입니다. 통신사 조회를 통해 `carrier.name` 및 `carrier.type`(`mobile`, `voip` 등)이 추가됩니다.
* `phone.phone_intelligence.score`는 숫자가 높을수록 위험도가 높은 0-100 위험 척도를 사용합니다. `phone_type_risk`(`Low`, `Medium`, `High`) 및 `phone_trust_index`(점수의 역수)는 파생된 뷰입니다.
* `phone.phone_intelligence`와 `phone.enrichment`는 동일한 정규화된 객체를 가리키는 호환성 별칭입니다. 새로운 연동에서는 `phone.enrichment`를 읽을 수 있습니다.
* `phone.matches`는 다른 사용자가 동일한 번호를 사용한 애플리케이션의 다른 세션을 나열합니다. 중복 계정 감지에 사용합니다.
* `request_id`는 API 세션 ID입니다. 결과를 향후 수신되는 webhook 또는 콘솔 활동과 연관 지어야 하는 경우 `vendor_data`와 함께 저장합니다.

> [!WARNING]
>
> `phone.phone_intelligence` 및 `phone.enrichment`는 최선의 노력으로 제공되는 필드입니다. 해당 번호, 국가 또는 요금제에 대해 사용 가능한 인텔리전스 데이터가 반환되지 않으면 조회가 완료되어도 두 필드가 모두 생략될 수 있습니다. 먼저 안정적인 정규화된 필드를 기반으로 규칙을 구성하고, 누락된 인텔리전스는 "안전함"이 아닌 "알 수 없음"으로 처리하십시오.

## 소셜 풋프린트 애드온

`enable_social`을 `true`로 설정하면 `phone` 아래 응답에 `phone_social` 블록이 추가됩니다. 여기에는 해당 전화번호가 등록된 온라인 플랫폼 목록이 카테고리별로 그룹화되어 표시되며, 요약 카운트 및 데이터 파트너가 반환하는 프로필 세부정보가 포함됩니다.

* `phone.phone_social.profiles_registered` 및 `phone.phone_social.profiles_checked`는 핵심 수치로, 평가된 플랫폼 중 전화번호 등록이 확인된 플랫폼 수를 나타냅니다.
* `phone.phone_social.registered_platforms` 및 `phone.phone_social.not_registered_platforms`는 각 플랫폼을 `category` 및 `scope`(`global`, 또는 지역별 플랫폼의 경우 `local`)와 함께 나열합니다.
* `phone.phone_social.categories`는 카테고리별 등록 건수 및 비율을 제공하며, `phone.phone_social.profiles`는 플랫폼에서 프로필 세부정보를 공개하는 경우 플랫폼별 프로필 상세 정보(이름, 사진 URL, 소개 텍스트, 공개 상태, 비즈니스 계정 플래그)를 전달합니다.
* 요약 지수(`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`)는 0-10 사이의 복합 지표입니다. 확인 결과 해당 데이터가 반환되지 않은 경우 모든 카운트는 `null`이 될 수 있습니다.

`profiles_registered: 0`은 실패가 아니라 유효한 결과입니다. 플랫폼 조회가 완료되었으나 어떤 플랫폼에서도 해당 전화번호가 발견되지 않았음을 의미하며, 이는 합성 신원의 일반적인 신호입니다. 이 endpoint 자체는 이에 대해 조치를 취하지 않으므로, 워크플로에서 `phone_no_social_presence_action`을 사용하여 이를 검토 또는 거부 판정으로 전환하십시오.

`enable_social`이 설정되지 않은 경우와 소셜 확인을 완료할 수 없는 경우 모두 해당 블록이 표시되지 않습니다. 소셜 확인을 완료할 수 없는 경우에는 비용이 청구되지 않습니다.

## 샌드박스 동작

샌드박스 키는 요청을 검증하고 결정론적인 승인 데이터를 반환합니다. OTP를 전송하거나 크레딧을 소비하지 않으며, 세션을 생성하거나 네트워크에 기여하지 않습니다. `enable_social`이 설정된 경우 결정론적인 `phone_social` 블록도 함께 반환합니다.

## 결제

Phone Risk API 호출은 정가 기준 \$0.04로, OTP가 전송되지 않으므로 전체 전화번호 인증보다 저렴합니다. 프로덕션 요청은 조회가 시작되면 청구 가능하며, 일부 최선 노력 필드를 사용할 수 없는 경우에도 비용이 청구됩니다.

소셜 풋프린트 애드온은 별도로 청구됩니다. 확인이 완료될 때마다 Phone Risk API 가격에 요청당 1건의 `phone_social` 단위가 추가됩니다. 조회 전 크레딧 확인에는 두 항목이 모두 포함됩니다.


## OpenAPI

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


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


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


        **결제.** 프로덕션 환경 호출에는 Phone Risk API 요금이 적용됩니다. 조회가 시작되면 일부 최선형 필드를 사용할 수
        없더라도 요청에 요금이 청구됩니다.


        **샌드박스.** 샌드박스 키는 요청을 검증하고 OTP 전송, 크레딧 소모, 세션 생성 또는 Networks 반영 없이 확정적인
        승인 데이터를 반환합니다.


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


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


        **소셜 발자국.** `enable_social`을 `true`로 설정하면 `phone_social` 블록이 추가됩니다. 여기에는
        이 번호가 등록된 온라인 플랫폼, 카테고리별 개수 및 사용 가능한 프로필 세부 정보가 포함됩니다.
        `profiles_registered: 0`은 플랫폼을 확인했으나 해당 번호가 등록된 곳이 없음을 의미하며, 유효하고 청구 대상인
        응답입니다. 추가 기능을 요청하지 않았거나 확인을 완료할 수 없는 경우에는 해당 블록이 생략되며, 이 경우 요금이 청구되지
        않습니다. 결제 시 이 endpoint 자체 가격에 요청당 `phone_social` 1단위가 추가됩니다.
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: 기본값을 사용해 번호 점수 산정
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: 신호, 국가 힌트 및 상관관계 ID를 포함한 점수 산정
                value:
                  phone_number: '+14155552671'
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: ios
                    device_model: iPhone17,2
                    os_version: 18.0.1
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0
                      Mobile/15E148 Safari/604.1
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            위험 평가가 완료되었습니다. 결정 사항은 `status`를 확인하십시오. 완료된 조회의 경우 HTTP는 항상
            `200`입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: 인텔리전스 커버리지가 포함된 유효한 휴대폰 번호
                  value:
                    request_id: 4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62
                    status: Approved
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: Example Mobile
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                      enrichment:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Number in review:
                  summary: 검토 대상으로 플래그 지정된 일회용 또는 가상 번호
                  value:
                    request_id: 8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f
                    status: In Review
                    phone:
                      status: In Review
                      phone_number_prefix: '+44'
                      phone_number: '7700900123'
                      full_number: '+447700900123'
                      country_code: GB
                      country_name: United Kingdom
                      carrier:
                        name: Example VoIP
                        type: voip
                      is_disposable: true
                      is_virtual: true
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                      enrichment:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                    vendor_data: lead-124
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/PhoneRiskValidationError'
        '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/phone/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "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.phone.assess_risk(
                phone_number="+14155552671",
            )
            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.phone.assessRisk({
              phone_number: "+14155552671",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\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.PhoneRiskRequest;

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

            var result = client.phone().assessRisk(PhoneRiskRequest.builder()
                    .phoneNumber("+14155552671")
                    .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->phone->assessRisk([
                'phone_number' => '+14155552671',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.phone.assess_risk(phone_number: "+14155552671")
            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.Phone.AssessRiskAsync(new PhoneRiskRequest
            {
                PhoneNumber = "+14155552671",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    PhoneRiskRequest:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          maxLength: 20
          description: 점수를 산정할 전화번호입니다. 유효성 검사를 거쳐 E.164로 정규화됩니다.
          example: '+14155552671'
        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 자체의 가격 외에 요청당 `phone_social` 1단위로 청구됩니다.
          example: true
    PhoneRiskResponse:
      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: 이 응답의 타임스탬프입니다.
        phone:
          type: object
          description: 전화번호 인증 응답에서 사용되는 것과 동일한 블록인 정규화된 전화번호 보고서입니다.
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: 이 전화번호에 대한 결정입니다. 최상위 `status`를 반영합니다.
            phone_number_prefix:
              type: string
              description: '`+`로 시작하는 국가 전화번호 코드(예: `+1`)입니다.'
              example: '+1'
            phone_number:
              type: string
              description: 국가 전화 코드를 제외한 국내 번호.
              example: '4155552671'
            full_number:
              type: string
              description: E.164 형식의 전체 번호입니다.
              example: '+14155552671'
            country_code:
              type: string
              nullable: true
              description: 해당 번호의 ISO 3166-1 alpha-2 국가 코드입니다.
              example: US
            country_name:
              type: string
              description: '`country_code`에서 파생된 전체 국가명입니다.'
              example: United States
            carrier:
              type: object
              nullable: true
              description: 해당 번호를 서비스하는 현재 네트워크입니다. 조회를 통해 통신사를 확인할 수 없는 경우 `null`입니다.
              properties:
                name:
                  type: string
                  description: 통신사 이름. 조회 시 식별할 수 없는 경우 빈 문자열입니다.
                type:
                  type: string
                  description: >-
                    조회 결과로 보고된 회선 유형: `mobile`, `fixed_line`, `voip`, `isp`,
                    `vpn`, `toll_free`, `premium_rate`, 또는 이와 유사한 유형.
            is_disposable:
              type: boolean
              description: 번호가 임시 번호 또는 버너 번호 서비스에 속하는 경우 `true`입니다.
            is_virtual:
              type: boolean
              description: 회선 유형이 가상(`voip`, `isp` 또는 `vpn`)인 경우 `true`입니다.
            verification_method:
              type: string
              nullable: true
              description: 기반이 되는 인증의 OTP 채널입니다. 코드를 보내지 않는 위험 조회의 경우 `null`입니다.
            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/PhoneMatchItem'
            phone_intelligence:
              $ref: '#/components/schemas/PhoneIntelligence'
            enrichment:
              $ref: '#/components/schemas/PhoneIntelligence'
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
    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 금액입니다.
    PhoneMatchItem:
      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`)입니다.
        phone_number:
          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`를 사용합니다.
    PhoneIntelligence:
      type: object
      description: >-
        정규화된 전화번호 인텔리전스 블록입니다. 이 조회에 대해 인텔리전스 애드온이 실행된 경우에만 존재하며, 존재하는 경우 동일한 값을
        가진 `enrichment` 별칭으로도 노출됩니다.
      properties:
        score:
          type: number
          nullable: true
          description: 정규화된 0-100 위험 점수입니다. 높을수록 위험합니다.
        phone_type_risk:
          type: string
          nullable: true
          description: 점수에서 파생된 `Low`, `Medium` 또는 `High`.
        phone_trust_index:
          type: number
          nullable: true
          description: 점수가 높을수록 좋은 대시보드를 위한 점수를 반전한 값입니다.
        network_stability_index:
          type: number
          nullable: true
          description: 회선 네트워크의 안정성입니다.
        is_disposable:
          type: boolean
          nullable: true
          description: 번호가 일회용 또는 가상 번호로 보이는 경우 `true`입니다.
        is_ported:
          type: boolean
          nullable: true
          description: 번호의 통신사가 변경된 경우 `true`입니다.
        is_recently_ported:
          type: boolean
          nullable: true
          description: 최근에 번호 이동이 발생한 경우 `true`입니다.
        carrier_type:
          type: string
          nullable: true
          description: '조회 결과로 보고된 회선 분류입니다(예: `mobile`).'
        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 코드, 방향, 메시지 및 영향 수준을 포함합니다. 새로운 코드가
            점진적으로 추가될 수 있으므로 알 수 없는 코드를 거부하지 마세요.
    PhoneSocialFootprint:
      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:
    PhoneRiskValidationError:
      description: 요청 유효성 검사에 실패했습니다.
      content:
        application/json:
          examples:
            Missing phone number:
              summary: 전화번호가 누락되었습니다
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: 유효하지 않은 전화번호
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: 유효하지 않은 신호 IP
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    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.