메인 콘텐츠로 건너뛰기
POST
curl
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와 함께 저장합니다.
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 단위가 추가됩니다. 조회 전 크레딧 확인에는 두 항목이 모두 포함됩니다.

인증

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 를 참고하십시오.

본문

application/json
phone_number
string
필수

점수를 산정할 전화번호입니다. 유효성 검사를 거쳐 E.164로 정규화됩니다.

Maximum string length: 20
예시:

"+14155552671"

country_code
string

인텔리전스 적용 범위를 위한 선택적 ISO 3166-1 alpha-2 또는 alpha-3 국가 힌트입니다.

Maximum string length: 3
예시:

"US"

signals
object

애플리케이션에서 관찰한 선택적 기기 및 네트워크 컨텍스트입니다. 모든 필드는 선택 사항입니다. 이를 전달하면 Networks의 세션 간 일치 감지 기능에 데이터가 제공됩니다.

vendor_data
string

이 요청에 대한 안정적인 참조값입니다. API 세션에 저장되며 응답에 그대로 반영됩니다.

metadata
object | null

귀하의 비민감 JSON 메타데이터입니다. API 세션에 저장되며 응답에 그대로 반환됩니다.

enable_social
boolean
기본값:false

true인 경우, 전화번호의 소셜 발자국(등록된 메시징, 소셜, 전자상거래 및 전문 플랫폼)도 조회합니다. 이 endpoint 자체의 가격 외에 요청당 phone_social 1단위로 청구됩니다.

예시:

true

응답

위험 평가가 완료되었습니다. 결정 사항은 status를 확인하십시오. 완료된 조회의 경우 HTTP는 항상 200입니다.

request_id
string<uuid>
필수

이 요청에 대해 생성된 API 세션의 ID입니다. 결과를 향후의 webhook이나 콘솔 활동과 연결해야 하는 경우 vendor_data와 함께 저장하세요.

status
enum<string>
필수

이 API 세션의 최종 결정입니다. 일반적으로 Approved이며, 위험 평가에 따라 In Review 또는 Declined가 생성될 수 있습니다.

사용 가능한 옵션:
Approved,
In Review,
Declined
created_at
string<date-time>
필수

이 응답의 타임스탬프입니다.

vendor_data
string | null

전송한 vendor_data의 에코 값이며, 전송하지 않은 경우 null입니다.

metadata
object | null

전송한 metadata의 에코 값이며, 전송하지 않은 경우 null입니다.

phone
object

전화번호 인증 응답에서 사용되는 것과 동일한 블록인 정규화된 전화번호 보고서입니다.

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