시작하기

글로벌 모바일 네트워크 인프라는 SS7 신호 네트워크로 알려진 시스템을 기반으로 운영됩니다. 이 네트워크는 통신사 간 가입자 데이터 교환, 통화 라우팅, SMS 전송, 실시간 모바일 연결 상태 업데이트를 지원합니다. 각 모바일 네트워크는 가입자의 필수 정보를 저장하는 핵심 데이터베이스인 홈 위치 등록기(HLR)를 유지 관리합니다.

HLR 조회 기술을 통해 기업은 이러한 등록기를 조회하여 모든 휴대전화 번호에 대한 실시간 연결 및 네트워크 세부 정보를 검색할 수 있습니다. 여기에는 전화기의 전원 상태, 현재 할당된 네트워크, 번호 이동 여부, 번호의 유효성 또는 비활성화 여부, 로밍 여부가 포함됩니다.

HLR Lookups API는 이러한 데이터에 대한 원활한 실시간 액세스를 제공하여 기업이 휴대전화 번호를 검증하고, 라우팅을 최적화하며, 고객 커뮤니케이션을 향상시킬 수 있도록 지원합니다. 이 문서는 HLR Lookups를 소프트웨어에 통합하여 실시간 모바일 인텔리전스를 자동으로 검색할 수 있도록 안내합니다.

HLR Lookups API 사용하기

HLR 조회 쿼리 실행은 빠르고 안전하며 간단합니다. 가입하고 API 키를 받으면 인증하고 POST /hlr-lookup을 통해 간단한 HTTP POST 요청으로 즉시 조회를 시작할 수 있습니다. 또는 개념 섹션에 설명된 대로 웹훅을 통해 서버로 결과를 다시 전송하는 빠른 비동기 API 요청을 선택하여 대용량 데이터 세트를 처리할 수 있습니다.

요청 예시

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

인증은 HTTP 헤더를 통해 제공되며, payload.json에는 최소한 다음 JSON 객체가 포함되어야 합니다:

페이로드 예시

{
   "msisdn": "+14156226819"
}

실행이 성공하면 지정된 휴대전화 번호에 대한 실시간 연결 세부 정보가 포함된 응답을 받게 됩니다.

성공 응답 application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

요청 및 응답 속성과 연결 상태에 대한 전체 세부 정보는 POST /hlr-lookup을 참조하세요.

추가 조회 서비스

번호 이동성(MNP) 조회

MNP 조회를 사용하여 실시간 연결 상태를 쿼리하지 않고도 네트워크 소유권 및 이동성 세부 정보를 확인할 수 있습니다. 번호의 MCCMNC만 필요한 경우 POST /mnp-lookup을 참조하세요.

번호 유형 탐지(NT) 조회

POST /nt-lookup을 통해 전화번호가 유선전화, 모바일, 프리미엄 요금, VoIP, 호출기 또는 기타 번호 체계 범위에 속하는지 확인할 수 있습니다.

소프트웨어 개발 키트(SDK)

HLR Lookups API는 모든 프로그래밍 언어의 REST 클라이언트와 호환되며, 빠른 시작을 위해 PHP, Ruby, NodeJS용 SDK를 GitHub에 공개했습니다.

도구

원활한 개발 경험을 보장하기 위해 브라우저 내 API 요청 및 웹훅 모니터링, IP 주소 화이트리스트, 강력한 인증 옵션, 인증 테스트 엔드포인트를 포함한 포괄적인 도구 모음을 제공합니다.

개발자가 아니신가요?

HLR 조회 및 번호 이동성 쿼리는 코딩 없이 수행할 수 있습니다. 엔터프라이즈 웹 클라이언트 및 브라우저 기반 리포팅 기능에 대해 자세히 알아보세요.

인증

보안 및 적절한 접근 제어를 위해 HLR Lookups API에 대한 대부분의 요청은 인증이 필요합니다. 엔드포인트는 공개 또는 보호됨으로 분류됩니다. 보호된 엔드포인트에 접근할 때는 Digest-Auth 또는 Basic-Auth 방식을 통해 API 키와 시크릿을 사용하여 요청을 인증해야 합니다. Digest-Auth가 더 안전한 옵션이며 강력히 권장됩니다. GET /auth-test 엔드포인트를 사용하여 인증 설정을 확인하세요.

API 키 및 API 시크릿

API 설정 페이지에서 API 키와 시크릿을 받으세요. 선호하는 인증 방법을 설정하고 보안 강화를 위해 IP 주소 화이트리스트를 활성화할 수도 있습니다. API 시크릿이 유출되었다고 의심되는 경우 언제든지 새로운 시크릿을 생성할 수 있습니다.

Basic 인증 Digest 인증 IP 화이트리스트

표준 Basic 인증은 구현이 쉽고 널리 지원됩니다. HTTP 요청에서 API 키와 시크릿을 user:pass 쌍으로 전달하여 인증할 수 있습니다.

HTTP Basic 인증

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

이는 Authorization 헤더를 전송합니다:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

권장: SHA256을 사용한 X-Basic 헤더

보안 강화를 위해 자격 증명을 base64로 직접 전송하는 대신 SHA256 해시를 전송할 수 있습니다. 이 방법을 사용하려면 YOUR_API_KEY:YOUR_API_SECRET 쌍의 해시를 계산하고 X-Basic 헤더를 통해 전송하세요:

Basic 인증 요청

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

Basic 인증 헤더

키	유형	설명
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`의 SHA256 해시. 해시에 콜론 기호(:)를 포함하세요.	필수

코드 예제

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth는 보호된 HLR Lookup API 엔드포인트에 대한 접근을 보호하는 데 권장되는 방법입니다. 각 요청에는 다음 헤더가 포함되어야 합니다: X-Digest-Key, X-Digest-Signature, X-Digest-Timestamp. 자세한 내용은 아래를 참조하세요.

요청 예제

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

요청 헤더

키	유형	설명
`X-Digest-Key`	string	고유한 HLR Lookups API 키입니다.	필수
`X-Digest-Signature`	string	고유한 인증 서명입니다(아래 참조).	필수
`X-Digest-Timestamp`	integer	현재 Unix 타임스탬프입니다(`GET /time` 참조).	필수

서명 생성

X-Digest-Signature는 API 시크릿을 공유 키로 사용하여 SHA256 HMAC 해시로 생성됩니다.

해시할 문자열은 다음과 같이 구성됩니다:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

. 기호는 문자열 연결을 나타냅니다.

Digest 서명 구성 요소

구성 요소	유형	설명
`ENDPOINT_PATH`	string	요청된 API 엔드포인트(예: `/auth-test`, 소문자)입니다.
`UNIX_TIMESTAMP`	integer	현재 Unix 타임스탬프(30초 이내여야 함). `GET /time`을 참조하세요.
`REQUEST_METHOD`	string	사용된 HTTP 메서드(예: `POST` 또는 `GET`)입니다.
`REQUEST_BODY`	string	요청 본문 데이터입니다. `GET` 요청의 경우 `null`로 설정하세요.

코드 예제

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

위로 스크롤

개념

HTTP REST API를 통해 모든 프로그래밍 언어 또는 시스템에서 HLR 조회를 구현하는 것은 간단하고 효율적입니다. 간단한 통합 프로세스를 통해 전화번호 유효성, 연결 상태 및 라우팅 세부정보에 대한 실시간 인사이트를 위해 모바일 네트워크를 즉시 조회할 수 있습니다.

적절한 API 선택은 특정 사용 사례에 따라 달라집니다. VoIP 전화, 사기 탐지 또는 SMS 라우팅과 같은 애플리케이션에 실시간 조회 결과가 필요한 경우 동기식 API가 최선의 선택입니다. 그러나 대량 처리, 일괄 조회 또는 대규모 데이터 검증과 관련된 사용 사례의 경우 비동기식 API가 대역폭 효율성과 일괄 조회 기능으로 최적화된 성능을 제공합니다.

속도, 정확성 및 비용 효율성을 최적화하기 위해 맞춤형 라우팅 옵션 중 하나를 사용하도록 API를 구성하세요. 또한 조회 결과를 스토리지에 저장하여 간편한 CSV 및 JSON 리포트 다운로드와 웹 인터페이스를 통한 고급 분석을 이용할 수 있습니다.

동기식 HLR 조회 API

POST /hlr-lookup 엔드포인트는 요청당 하나의 휴대전화 번호(MSISDN)를 처리하고 HTTP 응답 본문에서 즉시 결과를 반환합니다. 결과는 JSON 형식으로 제공되며 휴대전화 번호 검증, 통화 라우팅 및 SMS 메시지 전송을 포함한 실시간 애플리케이션에 이상적입니다.

동기식 API 호출은 직접적인 HTTP 요청과 응답으로 구성됩니다. 시스템은 요청당 단일 MSISDN(휴대전화 번호)을 제출하고 JSON 형식의 실시간 HLR 조회 결과가 포함된 즉각적인 응답을 받습니다. 이 API는 사기 탐지, VoIP 통화 라우팅 및 SMS 게이트웨이 최적화와 같이 즉각적인 검증 및 연결 확인이 필요한 사용 사례에 최적화되어 있습니다.

비동기 HLR 조회 API

POST /hlr-lookups 엔드포인트는 대량 및 고용량 처리를 위해 설계되었으며, 요청당 최대 1,000개의 MSISDN을 제출할 수 있습니다. 결과를 즉시 반환하는 대신 이 API는 자동화된 웹훅을 사용하여 서버로 결과를 점진적으로 전송합니다. 조회 결과는 HTTP POST 콜백을 통해 JSON 객체로 반환됩니다.

비동기식 API는 속도, 효율성 및 확장성에 최적화되어 있습니다. 동기식 호출과 관련된 네트워크 지연 문제를 제거하여 높은 처리량의 조회가 필요한 비즈니스에 이상적입니다. 시스템은 요청당 최대 1,000개의 MSISDN을 제출하고, 플랫폼은 이를 병렬로 처리하여 콜백당 최대 1,000개의 결과 배치로 HTTP 웹훅을 통해 서버로 결과를 전달합니다.

SDK (소프트웨어 개발 키트)

PHP, NodeJS, Ruby용 소프트웨어 개발 키트(SDK)는 통합 프로세스를 간소화하여 HLR Lookups API에 효율적이고 최소한의 노력으로 연결할 수 있도록 지원합니다.

이러한 SDK는 사전 구축된 함수, 인증 처리 및 구조화된 API 요청 템플릿을 제공하여 개발 시간을 단축하고 모범 사례를 보장합니다.

GitHub에서 사용 가능한 전체 SDK 목록을 확인하고 지금 바로 통합을 시작하세요.

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

GitHub에서 보기 README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

GitHub에서 보기 README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

GitHub에서 보기 README.md

위로 스크롤

POST/hlr-lookup보호됨

네트워크 사업자로부터 실시간 모바일 전화 연결성 및 이동성 데이터를 직접 제공하는 동기식 HLR 조회를 수행합니다. 이 엔드포인트는 시간에 민감한 애플리케이션에서 전화번호가 현재 연결 가능한 상태(연결됨)인지 또는 사용 불가능한 상태(전원 꺼짐)인지 즉시 확인해야 하는 실시간 트래픽 시나리오에 이상적입니다. 또한 활성 번호와 유효하지 않거나 알 수 없거나 가짜인 번호를 구별하는 데 도움이 됩니다.

즉각적인 결과가 필요하지 않은 대용량 데이터셋의 일괄 처리의 경우, 고속 배치 처리에 최적화된 비동기식 POST /hlr-lookups 사용을 고려하십시오.

주요 목적이 모바일 번호 이동성 데이터(MCCMNC) 조회이며 실시간 연결 상태가 필요하지 않은 경우, POST /mnp-lookup가 모바일 번호 이동성 쿼리를 위한 비용 효율적인 대안을 제공합니다.

요청 성공 응답 오류 응답 상태 참조

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

페이로드

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`msisdn`	string	조회할 모바일 전화번호(MSISDN)로, 국제 형식으로 제공되어야 합니다(예: +14156226819 또는 0014156226819). 국가 코드를 반드시 포함해야 합니다.	null	필수
`route`	string(3)	이 조회의 경로를 지정하는 선택적 3자 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 사용자 지정 라우팅 맵이 적용되거나 시스템이 이 조회에 가장 적합한 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

성공 응답 속성

이름	유형	설명	Null 허용
`id`	string(12)	이 조회 요청에 할당된 고유 식별자입니다.	false
`msisdn`	string	조회 대상 휴대전화 번호로, 국제 형식으로 표기됩니다(예: +14156226819 또는 0014156226819).	false
`connectivity_status`	string	번호의 연결 상태가 성공적으로 조회되었는지 여부를 나타냅니다. 가능한 값: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` 또는 `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	현재 해당 전화번호와 연결된 네트워크를 식별하는 5자리 또는 6자리 MCC(Mobile Country Code) 및 MNC(Mobile Network Code)입니다.	true
`mcc`	string(3)	전화번호가 등록된 국가를 식별하는 3자리 MCC(Mobile Country Code)입니다.	true
`mnc`	string(2\|3)	전화번호가 속한 특정 네트워크를 식별하는 2자리 또는 3자리 MNC(Mobile Network Code)입니다.	true
`imsi`	string	이 번호와 연결된 SIM 카드의 고유 식별자인 IMSI(International Mobile Subscriber Identity)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`msin`	string(10)	이동통신 사업자 데이터베이스 내의 MSIN(Mobile Subscription Identification Number)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`msc`	string(12)	현재 이 가입자의 통신을 처리하는 MSC(Mobile Switching Center)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`original_network_name`	string	이 번호와 연결된 원래(본래) 네트워크 사업자명입니다.	true
`original_country_name`	string	휴대전화 번호가 최초 등록된 국가의 전체 명칭으로, 영어로 제공됩니다.	true
`original_country_code`	string(2)	전화번호가 최초 할당된 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`original_country_prefix`	string	휴대전화 번호의 원래 국가에 해당하는 국제 전화 코드(국가 통화 코드)입니다.	true
`is_ported`	boolean	휴대전화 번호가 원래 네트워크에서 다른 사업자로 이동되었는지 여부를 나타냅니다.	true
`ported_network_name`	string	해당되는 경우, 휴대전화 번호가 이동된 네트워크 사업자명입니다.	true
`ported_country_name`	string	해당되는 경우, 휴대전화 번호가 이동된 국가명입니다.	true
`ported_country_code`	string(2)	해당되는 경우, 휴대전화 번호가 이동된 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`ported_country_prefix`	string	해당되는 경우, 휴대전화 번호가 이동된 국가의 국제 전화 코드(국가 통화 코드)입니다.	true
`is_roaming`	boolean	휴대전화 번호가 현재 해외 네트워크에서 로밍 중인지 여부를 나타냅니다. 로밍 상태 가용성은 이동통신 사업자에 따라 달라집니다.	true
`roaming_network_name`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 네트워크명입니다.	true
`roaming_country_name`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가명입니다.	true
`roaming_country_code`	string(2)	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가의 2자리 ISO 국가 코드입니다.	true
`roaming_country_prefix`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가의 국제 전화 코드(국가 통화 코드)입니다.	true
`cost`	string	문자열로 표시되는 십진수 값으로, EUR 단위의 조회 비용을 나타냅니다.	true
`timestamp`	string	조회가 완료된 시점을 나타내는 시간대를 포함한 W3C 형식의 타임스탬프입니다.	true
`storage`	string	조회 결과가 저장된 스토리지의 이름입니다. 이는 웹 인터페이스를 통해 사용 가능한 보고서명 및 CSV 다운로드에 해당합니다.	true
`route`	string(3)	이 조회 요청에 사용된 라우팅 방법을 나타내는 3자리 식별자입니다.	true
`processing_status`	string	조회의 처리 결과입니다. 가능한 값: `COMPLETED`(성공), `REJECTED`(네트워크 연결 불가, 요금 미부과) 또는 `FAILED`(처리 중 오류 발생).	false
`error_code`	integer	고객 지원을 위한 추가 진단 정보를 제공하는 선택적 내부 오류 코드입니다.	true
`error_description`	string	주어진 오류 코드(있는 경우)에 대한 간략한 설명으로, 영어 일반 텍스트로 제공됩니다.	true
`data_source`	string	이 요청에 사용된 데이터 소스입니다. 가능한 값: `LIVE_HLR`(실시간 HLR 조회) 또는 `MNP_DB`(정적 번호이동성 데이터베이스). 자세한 내용은 라우팅 옵션을 참조하세요.	false
`routing_instruction`	string	요청에 사용된 라우팅 지침을 설명하는 콜론으로 구분된 문자열입니다. 첫 번째 구성 요소는 경로를 지정한 경우 `STATIC`, 자동 라우팅의 경우 `AUTO`이며, 두 번째 구성 요소는 경로 식별자입니다. 자동 라우팅 요청의 경우 세 번째 구성 요소는 라우팅 결정의 기반이 되는 출처를 표시합니다(예: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

상태	설명
CONNECTED	유효한 번호이며, 대상 단말기가 현재 이동통신망에 연결되어 있습니다. 통화, SMS 및 기타 서비스가 수신자에게 정상적으로 전달됩니다.
ABSENT	유효한 번호이지만, 대상 단말기가 전원이 꺼져 있거나 일시적으로 네트워크 권역 밖에 있습니다. 단말기가 네트워크에 재연결될 때까지 메시지나 통화가 전달되지 않을 수 있습니다.
INVALID_MSISDN	유효하지 않은 번호이거나 현재 이동통신망의 가입자에게 할당되지 않은 번호입니다. 이 번호로의 통화 및 메시지 전송이 실패합니다.
UNDETERMINED	번호의 연결 상태를 확인할 수 없습니다. 이는 유효하지 않은 번호, SS7 오류 응답 또는 대상 네트워크 사업자와의 연결 부족으로 인한 것일 수 있습니다. 추가 진단을 위해 오류 코드 및 설명 필드를 확인하시기 바랍니다.

위로 스크롤

POST/hlr-lookups보호됨

비동기 HLR 조회 배치를 시작하여 네트워크 사업자로부터 실시간 휴대전화 연결성 및 이동성 데이터를 조회합니다. 결과는 웹훅을 통해 귀하의 서버로 전달됩니다. 이 방식은 데이터베이스 정리 및 검증과 같이 즉각적인 응답이 필요하지 않은 대량의 번호를 처리하는 데 최적화되어 있습니다. 통화 라우팅이나 SMS 전송과 같은 실시간 애플리케이션의 경우 POST /hlr-lookup 엔드포인트 사용을 권장합니다.

이 엔드포인트는 현재 연결 가능한(연결됨) 전화번호 또는 사용 불가능한(전원 꺼짐) 전화번호를 식별하고, 유효하지 않거나 할당되지 않은 가짜 번호를 필터링하는 대량 처리에 이상적입니다. 또한 연결성 세부정보와 함께 실시간 이동성 상태(MCCMNC)를 제공합니다.

이 엔드포인트를 사용하기 전에 조회 결과를 비동기적으로 수신할 웹훅 URL이 구성되어 있는지 확인하십시오. API 설정에서 설정할 수 있습니다.

요청 성공 응답 오류 응답 웹훅 상태 참조

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

페이로드

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`msisdns`	array	국제 형식의 휴대전화번호(MSISDN) 배열입니다(예: +14156226819 또는 0014156226819). 요청당 최대 1000개의 번호를 포함할 수 있습니다.	null	필수
`route`	string(3)	이 조회의 경로를 지정하는 선택적 3자 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 사용자 지정 라우팅 맵이 적용되거나 시스템이 이 조회에 가장 적합한 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`accepted`	array	처리가 승인된 고유 식별자 및 MSISDN을 포함하는 객체 목록입니다.	false
`accepted_count`	integer	처리가 성공적으로 승인된 총 MSISDN 수입니다.	false
`rejected`	array	일반적으로 유효하지 않은 번호로 인해 처리가 거부된 고유 식별자 및 MSISDN을 포함하는 객체 목록입니다. 거부된 항목에 대해서는 요금이 부과되지 않습니다.	false
`rejected_count`	integer	유효성 검사 오류로 인해 거부된 총 MSISDN 수입니다.	false
`total_count`	integer	처리를 위해 제출된 승인 및 거부된 MSISDN의 총 개수입니다.	false
`cost`	string	승인된 조회에 대한 총 비용을 EUR로 나타내는 문자열 형식의 십진수 값입니다.	false
`storage`	string	조회 결과가 추가되는 저장소의 이름으로, 웹 인터페이스를 통한 보고서 작성 및 CSV 다운로드에 사용됩니다.	false
`route`	string(3\|4)	이 조회 요청에 사용된 라우트를 지정하는 3자리 또는 4자리 식별자입니다. 번호 기반 자동 라우팅이 요청된 경우 AUTO를 포함합니다.	false
`webhook_urls`	array	API 설정에 구성된 웹훅 URL입니다. 결과는 여기로 전송됩니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

웹훅 처리

제출이 완료되면 플랫폼이 제공된 전화번호를 처리하기 시작하고, 결과를 귀하의 서버에 사전 지정된 웹훅 URL로 전송합니다. 결과는 요청 본문에 JSON 객체가 포함된 HTTP POST 요청으로 전송됩니다.

인증

X-Signatures HTTP 헤더를 검사하여 웹훅을 인증하세요.

X-Signatures 헤더에는 세미콜론으로 구분된 서명 목록이 포함되어 있습니다. 목록의 각 서명은 귀하의 계정에 구성된 API 시크릿 중 하나를 사용하여 생성됩니다. 웹훅을 검증하려면 API 키, 시크릿, 원시 HTTP 본문을 사용하여 SHA-256 해시를 생성한 다음, 목록의 서명과 비교하세요.

일치하는 경우 요청이 진본이며 귀하가 관리하는 시크릿으로 서명되었음을 확인합니다.

코드 예제

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

헤더에 제공된 서명 중 하나가 API 키, 시크릿, HTTP 본문을 연결한 문자열에 대해 계산된 SHA256 해시와 일치하면 요청이 유효합니다.

수신 확인

귀하의 서버는 성공적인 수신을 확인하기 위해 HTTP 상태 코드 200 OK로 응답해야 합니다. 다른 응답 코드가 반환되거나, 타임아웃이 발생하거나(10초), 기타 전송 문제가 발생하면 시스템은 1분 후 자동으로 웹훅을 재시도합니다. 요청이 계속 실패하면 지수 백오프 전략에 따라 재시도가 이루어지며, 이후 시도는 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024분 후에 진행됩니다.

이 재시도 메커니즘은 귀하의 인프라로 조회 결과를 전송하는 데 있어 최대한의 안정성을 보장합니다. 일시적인 네트워크 문제나 서버 다운타임으로 인한 데이터 손실 위험을 최소화합니다.

웹훅 페이로드

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

웹훅 페이로드 속성

JSON 객체는 type => HLR 속성과 함께 아래 문서화된 조회 객체 목록을 포함하는 results 속성을 포함합니다.

이름	유형	설명	Null 허용
`id`	string(12)	이 조회 요청에 할당된 고유 식별자입니다.	false
`msisdn`	string	조회 대상 휴대전화 번호로, 국제 형식으로 표기됩니다(예: +14156226819 또는 0014156226819).	false
`connectivity_status`	string	번호의 연결 상태가 성공적으로 조회되었는지 여부를 나타냅니다. 가능한 값: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` 또는 `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	현재 해당 전화번호와 연결된 네트워크를 식별하는 5자리 또는 6자리 MCC(Mobile Country Code) 및 MNC(Mobile Network Code)입니다.	true
`mcc`	string(3)	전화번호가 등록된 국가를 식별하는 3자리 MCC(Mobile Country Code)입니다.	true
`mnc`	string(2\|3)	전화번호가 속한 특정 네트워크를 식별하는 2자리 또는 3자리 MNC(Mobile Network Code)입니다.	true
`imsi`	string	이 번호와 연결된 SIM 카드의 고유 식별자인 IMSI(International Mobile Subscriber Identity)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`msin`	string(10)	이동통신 사업자 데이터베이스 내의 MSIN(Mobile Subscription Identification Number)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`msc`	string(12)	현재 이 가입자의 통신을 처리하는 MSC(Mobile Switching Center)입니다. 가용성은 네트워크 구성에 따라 달라집니다.	true
`original_network_name`	string	이 번호와 연결된 원래(본래) 네트워크 사업자명입니다.	true
`original_country_name`	string	휴대전화 번호가 최초 등록된 국가의 전체 명칭으로, 영어로 제공됩니다.	true
`original_country_code`	string(2)	전화번호가 최초 할당된 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`original_country_prefix`	string	휴대전화 번호의 원래 국가에 해당하는 국제 전화 코드(국가 통화 코드)입니다.	true
`is_ported`	boolean	휴대전화 번호가 원래 네트워크에서 다른 사업자로 이동되었는지 여부를 나타냅니다.	true
`ported_network_name`	string	해당되는 경우, 휴대전화 번호가 이동된 네트워크 사업자명입니다.	true
`ported_country_name`	string	해당되는 경우, 휴대전화 번호가 이동된 국가명입니다.	true
`ported_country_code`	string(2)	해당되는 경우, 휴대전화 번호가 이동된 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`ported_country_prefix`	string	해당되는 경우, 휴대전화 번호가 이동된 국가의 국제 전화 코드(국가 통화 코드)입니다.	true
`is_roaming`	boolean	휴대전화 번호가 현재 해외 네트워크에서 로밍 중인지 여부를 나타냅니다. 로밍 상태 가용성은 이동통신 사업자에 따라 달라집니다.	true
`roaming_network_name`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 네트워크명입니다.	true
`roaming_country_name`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가명입니다.	true
`roaming_country_code`	string(2)	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가의 2자리 ISO 국가 코드입니다.	true
`roaming_country_prefix`	string	해당되는 경우, 휴대전화 번호가 현재 로밍 중인 국가의 국제 전화 코드(국가 통화 코드)입니다.	true
`cost`	string	문자열로 표시되는 십진수 값으로, EUR 단위의 조회 비용을 나타냅니다.	true
`timestamp`	string	조회가 완료된 시점을 나타내는 시간대를 포함한 W3C 형식의 타임스탬프입니다.	true
`storage`	string	조회 결과가 저장된 스토리지의 이름입니다. 이는 웹 인터페이스를 통해 사용 가능한 보고서명 및 CSV 다운로드에 해당합니다.	true
`route`	string(3)	이 조회 요청에 사용된 라우팅 방법을 나타내는 3자리 식별자입니다.	true
`processing_status`	string	조회의 처리 결과입니다. 가능한 값: `COMPLETED`(성공), `REJECTED`(네트워크 연결 불가, 요금 미부과) 또는 `FAILED`(처리 중 오류 발생).	false
`error_code`	integer	고객 지원을 위한 추가 진단 정보를 제공하는 선택적 내부 오류 코드입니다.	true
`error_description`	string	주어진 오류 코드(있는 경우)에 대한 간략한 설명으로, 영어 일반 텍스트로 제공됩니다.	true
`data_source`	string	이 요청에 사용된 데이터 소스입니다. 가능한 값: `LIVE_HLR`(실시간 HLR 조회) 또는 `MNP_DB`(정적 번호이동성 데이터베이스). 자세한 내용은 라우팅 옵션을 참조하세요.	false
`routing_instruction`	string	요청에 사용된 라우팅 지침을 설명하는 콜론으로 구분된 문자열입니다. 첫 번째 구성 요소는 경로를 지정한 경우 `STATIC`, 자동 라우팅의 경우 `AUTO`이며, 두 번째 구성 요소는 경로 식별자입니다. 자동 라우팅 요청의 경우 세 번째 구성 요소는 라우팅 결정의 기반이 되는 출처를 표시합니다(예: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

상태	설명
CONNECTED	유효한 번호이며, 대상 단말기가 현재 이동통신망에 연결되어 있습니다. 통화, SMS 및 기타 서비스가 수신자에게 정상적으로 전달됩니다.
ABSENT	유효한 번호이지만, 대상 단말기가 전원이 꺼져 있거나 일시적으로 네트워크 권역 밖에 있습니다. 단말기가 네트워크에 재연결될 때까지 메시지나 통화가 전달되지 않을 수 있습니다.
INVALID_MSISDN	유효하지 않은 번호이거나 현재 이동통신망의 가입자에게 할당되지 않은 번호입니다. 이 번호로의 통화 및 메시지 전송이 실패합니다.
UNDETERMINED	번호의 연결 상태를 확인할 수 없습니다. 이는 유효하지 않은 번호, SS7 오류 응답 또는 대상 네트워크 사업자와의 연결 부족으로 인한 것일 수 있습니다. 추가 진단을 위해 오류 코드 및 설명 필드를 확인하시기 바랍니다.

위로 스크롤

POST/mnp-lookup보호됨

동기식 MNP 조회를 실행하여 번호 이동성 및 네트워크 정보를 제공합니다. 이 엔드포인트는 특정 휴대전화 번호의 현재 MCCMNC를 추출하고 원래 네트워크와 현재 네트워크를 실시간으로 파악하는 것이 주요 목표인 경우에 적합합니다.

즉각적인 결과가 필요하지 않은 대용량 데이터셋의 일괄 처리의 경우, 고속 배치 처리에 최적화된 비동기식 POST /mnp-lookups 사용을 고려하십시오.

MNP 조회는 번호 이동성 및 네트워크 정보를 안정적으로 확인하지만, 대상 휴대전화가 현재 네트워크에 연결되어 있고 도달 가능한지 여부는 표시하지 않습니다. 실시간 연결 상태 정보를 확인하려면 POST /hlr-lookup 엔드포인트를 사용하시기 바랍니다.

요청 성공 응답 오류 응답

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

페이로드

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`msisdn`	string	조회할 모바일 전화번호(MSISDN)로, 국제 형식으로 제공되어야 합니다(예: +14156226819 또는 0014156226819). 국가 코드를 반드시 포함해야 합니다.	null	필수
`route`	string(3)	이 조회의 경로를 지정하는 선택적 3자 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 사용자 지정 라우팅 맵이 적용되거나 시스템이 이 조회에 가장 적합한 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

성공 응답 속성

이름	유형	설명	Null 허용
`id`	string(12)	이 조회에 대한 고유한 12자리 식별자입니다.	false
`msisdn`	string	이 조회 요청에서 평가된 휴대전화 번호입니다.	false
`query_status`	string	이동성 및 네트워크 정보 검색의 성공 여부를 나타냅니다. 가능한 값은 `OK` 또는 `FAILED`입니다.	false
`mccmnc`	string(5\|6)	휴대전화 번호가 현재 속한 네트워크를 식별하는 5자리 또는 6자리 MCCMNC(이동 국가 코드 및 이동 네트워크 코드 튜플)입니다.	true
`mcc`	string(3)	휴대전화 번호의 현재 네트워크와 연결된 국가를 나타내는 3자리 MCC(이동 국가 코드)입니다.	true
`mnc`	string(2\|3)	휴대전화 번호의 현재 네트워크 사업자를 식별하는 2자리 또는 3자리 MNC(이동 네트워크 코드)입니다.	true
`is_ported`	boolean	전화번호가 원래 네트워크에서 새로운 사업자로 이동되었는지 여부를 나타냅니다.	true
`original_network_name`	string	조회된 휴대전화 번호의 원래 네트워크 사업자 이름을 지정하는 임의의 문자열(영어)입니다.	true
`original_country_name`	string	조회된 휴대전화 번호의 원래 국가를 나타내는 임의의 문자열(영어)입니다.	true
`original_country_code`	string(2)	조회된 휴대전화 번호의 원래 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`original_country_prefix`	string	조회된 휴대전화 번호와 연결된 원래 국가의 국가번호입니다.	true
`ported_network_name`	string	조회된 휴대전화 번호가 이동된 네트워크 사업자를 지정합니다(해당되는 경우).	true
`ported_country_name`	string	조회된 휴대전화 번호가 이동된 국가를 지정합니다(해당되는 경우).	true
`ported_country_code`	string(2)	조회된 휴대전화 번호가 이동된 국가를 나타내는 2자리 ISO 국가 코드입니다(해당되는 경우).	true
`ported_country_prefix`	string	조회된 휴대전화 번호가 이동된 국가의 국가번호입니다(해당되는 경우).	true
`extra`	string	전화번호에 대한 선택적 추가 세부정보를 제공하는 임의의 문자열입니다.	true
`cost`	string	이 조회의 EUR 비용을 나타내는 문자열로 표시된 십진수 값입니다.	true
`timestamp`	string	조회가 완료된 시점을 나타내는 시간대 정보를 포함한 W3C 형식의 타임스탬프입니다.	true
`storage`	string	조회 결과가 추가된 저장소 이름(또는 보고서 이름)입니다. CSV 다운로드 및 웹 인터페이스를 통한 보고에 사용됩니다.	true
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자리 식별자입니다.	true
`error_code`	integer	고객 지원 진단을 위한 추가 컨텍스트를 제공하는 선택적 내부 오류 코드입니다.	true

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

POST/mnp-lookups보호됨

비동기 MNP(번호 이동성) 조회를 일괄 실행하여 현재 MCCMNC를 검색하고 원래 네트워크와 현재 네트워크를 실시간으로 정확히 파악합니다. 결과는 웹훅을 통해 귀하의 서버로 전달됩니다. 이 방식은 데이터베이스 정리 및 검증과 같이 즉각적인 응답이 필요하지 않은 대량의 번호를 처리하는 데 최적화되어 있습니다. 통화 라우팅이나 SMS 전송과 같은 실시간 애플리케이션의 경우 POST /mnp-lookup 엔드포인트 사용을 권장합니다.

MNP 조회는 번호 이동성 및 네트워크 정보를 안정적으로 확인하지만, 대상 휴대전화가 현재 네트워크에 연결되어 있고 도달 가능한지 여부는 표시하지 않습니다. 실시간 연결 상태 정보를 확인하려면 POST /hlr-lookups 엔드포인트를 사용하시기 바랍니다.

이 엔드포인트를 사용하기 전에 조회 결과를 비동기적으로 수신할 웹훅 URL이 구성되어 있는지 확인하십시오. API 설정에서 설정할 수 있습니다.

요청 성공 응답 오류 응답 웹훅

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

페이로드

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`msisdns`	array	국제 형식의 휴대전화번호(MSISDN) 배열입니다(예: +14156226819 또는 0014156226819). 요청당 최대 1000개의 번호를 포함할 수 있습니다.	null	필수
`route`	string(3)	이 조회에 대한 경로를 지정하는 선택적 3자 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 사용자 정의 라우팅 맵이 적용되거나 시스템이 이 요청에 대한 최적의 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`accepted`	array	처리가 승인된 고유 식별자 및 MSISDN을 포함하는 객체 목록입니다.	false
`accepted_count`	integer	처리가 성공적으로 승인된 총 MSISDN 수입니다.	false
`rejected`	array	일반적으로 유효하지 않은 번호로 인해 처리가 거부된 고유 식별자 및 MSISDN을 포함하는 객체 목록입니다. 거부된 항목에 대해서는 요금이 부과되지 않습니다.	false
`rejected_count`	integer	유효성 검사 오류로 인해 거부된 총 MSISDN 수입니다.	false
`total_count`	integer	처리를 위해 제출된 승인 및 거부된 MSISDN의 총 개수입니다.	false
`cost`	string	승인된 조회에 대한 총 비용을 EUR로 나타내는 문자열 형식의 십진수 값입니다.	false
`storage`	string	조회 결과가 추가되는 저장소의 이름으로, 웹 인터페이스를 통한 보고서 작성 및 CSV 다운로드에 사용됩니다.	false
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자리 식별자입니다.	false
`webhook_urls`	array	API 설정에 구성된 웹훅 URL입니다. 결과는 여기로 전송됩니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

웹훅 처리

제출이 완료되면 플랫폼이 제공된 전화번호를 처리하기 시작하고, 결과를 귀하의 서버에 사전 지정된 웹훅 URL로 전송합니다. 결과는 요청 본문에 JSON 객체가 포함된 HTTP POST 요청으로 전송됩니다.

인증

X-Signatures HTTP 헤더를 검사하여 웹훅을 인증하세요.

X-Signatures 헤더에는 세미콜론으로 구분된 서명 목록이 포함되어 있습니다. 목록의 각 서명은 귀하의 계정에 구성된 API 시크릿 중 하나를 사용하여 생성됩니다. 웹훅을 검증하려면 API 키, 시크릿, 원시 HTTP 본문을 사용하여 SHA-256 해시를 생성한 다음, 목록의 서명과 비교하세요.

일치하는 경우 요청이 진본이며 귀하가 관리하는 시크릿으로 서명되었음을 확인합니다.

코드 예제

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

헤더에 제공된 서명 중 하나가 API 키, 시크릿, HTTP 본문을 연결한 문자열에 대해 계산된 SHA256 해시와 일치하면 요청이 유효합니다.

수신 확인

귀하의 서버는 성공적인 수신을 확인하기 위해 HTTP 상태 코드 200 OK로 응답해야 합니다. 다른 응답 코드가 반환되거나, 타임아웃이 발생하거나(10초), 기타 전송 문제가 발생하면 시스템은 1분 후 자동으로 웹훅을 재시도합니다. 요청이 계속 실패하면 지수 백오프 전략에 따라 재시도가 이루어지며, 이후 시도는 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024분 후에 진행됩니다.

이 재시도 메커니즘은 귀하의 인프라로 조회 결과를 전송하는 데 있어 최대한의 안정성을 보장합니다. 일시적인 네트워크 문제나 서버 다운타임으로 인한 데이터 손실 위험을 최소화합니다.

웹훅 페이로드

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

웹훅 페이로드 속성

JSON 객체는 type => MNP 속성과 함께 아래 문서화된 조회 객체 목록을 포함하는 results 속성을 포함합니다.

이름	유형	설명	Null 허용
`id`	string(12)	이 조회에 대한 고유한 12자리 식별자입니다.	false
`msisdn`	string	이 조회 요청에서 평가된 휴대전화 번호입니다.	false
`query_status`	string	이동성 및 네트워크 정보 검색의 성공 여부를 나타냅니다. 가능한 값은 `OK` 또는 `FAILED`입니다.	false
`mccmnc`	string(5\|6)	휴대전화 번호가 현재 속한 네트워크를 식별하는 5자리 또는 6자리 MCCMNC(이동 국가 코드 및 이동 네트워크 코드 튜플)입니다.	true
`mcc`	string(3)	휴대전화 번호의 현재 네트워크와 연결된 국가를 나타내는 3자리 MCC(이동 국가 코드)입니다.	true
`mnc`	string(2\|3)	휴대전화 번호의 현재 네트워크 사업자를 식별하는 2자리 또는 3자리 MNC(이동 네트워크 코드)입니다.	true
`is_ported`	boolean	전화번호가 원래 네트워크에서 새로운 사업자로 이동되었는지 여부를 나타냅니다.	true
`original_network_name`	string	조회된 휴대전화 번호의 원래 네트워크 사업자 이름을 지정하는 임의의 문자열(영어)입니다.	true
`original_country_name`	string	조회된 휴대전화 번호의 원래 국가를 나타내는 임의의 문자열(영어)입니다.	true
`original_country_code`	string(2)	조회된 휴대전화 번호의 원래 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`original_country_prefix`	string	조회된 휴대전화 번호와 연결된 원래 국가의 국가번호입니다.	true
`ported_network_name`	string	조회된 휴대전화 번호가 이동된 네트워크 사업자를 지정합니다(해당되는 경우).	true
`ported_country_name`	string	조회된 휴대전화 번호가 이동된 국가를 지정합니다(해당되는 경우).	true
`ported_country_code`	string(2)	조회된 휴대전화 번호가 이동된 국가를 나타내는 2자리 ISO 국가 코드입니다(해당되는 경우).	true
`ported_country_prefix`	string	조회된 휴대전화 번호가 이동된 국가의 국가번호입니다(해당되는 경우).	true
`extra`	string	전화번호에 대한 선택적 추가 세부정보를 제공하는 임의의 문자열입니다.	true
`cost`	string	이 조회의 EUR 비용을 나타내는 문자열로 표시된 십진수 값입니다.	true
`timestamp`	string	조회가 완료된 시점을 나타내는 시간대 정보를 포함한 W3C 형식의 타임스탬프입니다.	true
`storage`	string	조회 결과가 추가된 저장소 이름(또는 보고서 이름)입니다. CSV 다운로드 및 웹 인터페이스를 통한 보고에 사용됩니다.	true
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자리 식별자입니다.	true
`error_code`	integer	고객 지원 진단을 위한 추가 컨텍스트를 제공하는 선택적 내부 오류 코드입니다.	true

위로 스크롤

POST/nt-lookup보호됨

동기식 번호 유형(NT) 조회를 실행합니다. 이 엔드포인트는 제공된 전화번호가 유선전화, 이동전화, 프리미엄 요금, VoIP, 페이저 또는 기타 번호 체계 범위에 속하는지 실시간으로 확인하는 것이 주요 목적인 경우에 적합합니다.

NT 조회는 전화번호 유형을 안정적으로 감지하지만, 대상 번호가 현재 네트워크에 연결되어 있고 연결 가능한지 여부는 표시하지 않습니다. 실시간 연결 정보를 확인하려면 POST /hlr-lookup 엔드포인트를 사용하시기 바랍니다.

정확한 네트워크 및 이동성 정보(MCCMNC)가 필요하지만 실시간 연결 상태는 필요하지 않은 경우, 이동전화번호 이동성 조회를 위해 POST /mnp-lookup 엔드포인트를 사용하시기 바랍니다.

요청 성공 응답 오류 응답 유형 참조

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

페이로드

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`number`	string	국제 형식의 전화번호(예: +4989702626 또는 004989702626).	null	mandatory
`route`	string(3)	이 조회의 경로를 지정하는 선택적 3자리 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 맞춤 라우팅 맵이 적용되거나 시스템이 이 요청에 대한 최적의 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

성공 응답 속성

이름	유형	설명	Null 허용
`id`	string(12)	이 조회 요청에 할당된 고유 식별자입니다.	false
`number`	string	이 조회 요청 중 평가된 전화번호입니다.	false
`number_type`	string	감지된 번호 유형입니다. 가능한 값: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN`	false
`query_status`	string	번호 유형 정보를 성공적으로 획득했는지 여부를 나타냅니다. 성공 시 `OK`를, 조회 실패 시 `FAILED`를 반환합니다.	false
`is_valid`	boolean	전화번호가 구문적으로 유효한지 여부를 나타냅니다.	true
`invalid_reason`	string	전화번호가 유효하지 않은 이유를 영문으로 설명하는 일반 텍스트 메시지입니다(예: "too short" 또는 "invalid prefix"). 번호가 유효한 경우 `null`을 반환합니다.	true
`is_possibly_ported`	boolean	전화번호가 원래 통신사에서 다른 통신사로 이동했을 가능성이 있는지 여부를 나타냅니다. 정확한 번호이동 정보는 MNP 조회를 이용하시기 바랍니다.	true
`is_vanity_number`	boolean	전화번호가 알파벳 문자를 포함하는 배니티 번호인지 여부를 나타냅니다.	true
`qualifies_for_hlr_lookup`	boolean	HLR 조회를 통한 추가 쿼리가 가능한 전화번호인지 여부를 나타냅니다.	true
`mccmnc`	string(5\|6)	휴대전화번호의 원래 네트워크를 식별하는 MCCMNC 튜플(이동통신 국가 코드 및 이동통신 네트워크 코드)을 나타내는 5자리 또는 6자리 문자열입니다.	true
`mcc`	string(3)	전화번호의 원래 이동통신 네트워크와 연결된 국가를 식별하는 MCC(이동통신 국가 코드)를 나타내는 3자리 문자열입니다.	true
`mnc`	string(2\|3)	전화번호의 원래 이동통신 네트워크 사업자를 식별하는 MNC(이동통신 네트워크 코드)를 나타내는 2자리 또는 3자리 문자열입니다.	true
`original_network_name`	string	조회된 휴대전화번호의 원래 네트워크 사업자 이름을 영문으로 지정하는 임의의 일반 텍스트 문자열입니다.	true
`original_country_name`	string	조회된 휴대전화번호와 연결된 원래 국가를 영문으로 지정하는 임의의 일반 텍스트 문자열입니다.	true
`original_country_code`	string(2)	조회된 휴대전화번호의 원래 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`regions`	array	이 전화번호와 연결된 지리적 지역을 영문으로 지정하는 사람이 읽을 수 있는 문자열 목록입니다.	true
`timezones`	array	이 전화번호와 연결된 시간대(Olson 형식) 목록입니다.	true
`info_text`	string	전화번호에 대한 추가 정보를 포함할 수 있는 임의의 문자열입니다.	true
`cost`	string	이 조회의 비용(EUR)을 나타내는 문자열 형식의 십진수 값입니다.	true
`timestamp`	string	조회가 완료된 시간을 나타내는 W3C 형식의 타임스탬프(시간대 포함)입니다.	true
`storage`	string	조회 결과가 추가된 저장소 이름을 지정합니다. 이는 웹 인터페이스를 통한 CSV 다운로드 및 분석에 사용되는 리포트 이름과 일치합니다.	true
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자리 식별자입니다.	true

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

유형	설명
LANDLINE	유선 전화번호입니다.
MOBILE	이동전화번호입니다. HLR 조회를 통해 연결 상태, 네트워크, 번호이동성 및 로밍 정보를 확인할 수 있습니다.
MOBILE_OR_LANDLINE	유선 또는 이동전화번호입니다. HLR 조회가 가능할 수 있습니다.
TOLL_FREE	무료 전화번호입니다.
PREMIUM_RATE	추가 요금이 부과되는 프리미엄 요금 전화번호입니다.
SHARED_COST	공동 부담 전화번호입니다. 일반적으로 프리미엄 요금 전화번호보다 저렴합니다.
VOIP	인터넷 전화번호입니다. TSoIP 전화번호(IP 기반 전화 서비스)를 포함합니다.
PAGER	무선호출기 전화번호입니다. 일반적으로 음성 통화 기능이 없습니다.
UAN	통합 접속 번호(대표번호)입니다. 특정 사무실로 연결될 수 있지만 회사에서 하나의 번호를 사용할 수 있습니다.
VOICEMAIL	음성사서함 전화번호입니다.
UNKNOWN	번호 유형을 확인할 수 없습니다.

위로 스크롤

POST/nt-lookups 보호됨

이 엔드포인트는 일련의 비동기 번호 유형 조회를 실행하며, 결과는 웹훅을 통해 귀하의 서버로 전송됩니다. 주어진 전화번호가 유선, 모바일, 프리미엄 요금, VoIP, 페이저 또는 기타 번호 체계 범위에 속하는지 확인하는 것이 주요 목적인 경우 적합합니다. 대량의 번호를 빠르게 처리하도록 최적화되어 있어, 대량 작업(예: 데이터베이스 정리)에 이상적입니다. 실시간 트래픽 및 시간이 중요한 사용 사례의 경우 POST /nt-lookup 엔드포인트를 사용하시기 바랍니다.

이 엔드포인트를 호출하려면 API 설정에서 웹훅 URL을 먼저 지정해야 합니다.

요청 성공 응답 오류 응답 웹훅 유형 참조

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

페이로드

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

요청 매개변수

키	유형	설명	기본값	필수
`numbers`	array	국제 형식의 전화번호 배열(예: +14156226819 또는 004989702626). 요청당 최대 1000개의 번호를 포함할 수 있습니다.	null	필수
`route`	string(3)	이 조회의 경로를 지정하는 선택적 3자 식별자입니다. `null`로 설정하거나 이 매개변수를 생략하면 사용자 지정 라우팅 맵이 적용되거나 시스템이 이 요청에 가장 적합한 경로를 자동으로 결정합니다.	null	선택사항
`storage`	string	수동 검토, 분석 및 보고를 위해 결과가 저장될 리포트를 지정하는 선택적 저장소 식별자입니다. 시스템은 현재 월의 타임스탬프를 자동으로 추가합니다. 생략하거나 `null`로 설정하면 시스템이 보고 목적으로 결과를 월별로 자동 그룹화합니다.	null	선택사항

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`accepted`	array	처리가 승인된 고유 식별자와 전화번호를 포함하는 객체 배열입니다.	false
`accepted_count`	integer	처리가 승인된 전화번호의 총 개수입니다.	false
`rejected`	array	처리가 거부된 고유 식별자와 전화번호를 포함하는 객체 배열입니다. 일반적으로 이러한 번호는 유효하지 않으며 요금이 부과되지 않습니다.	false
`rejected_count`	integer	처리가 거부된 전화번호의 총 개수입니다.	false
`total_count`	integer	처리를 위해 제출된 승인 및 거부된 전화번호의 총 개수입니다.	false
`cost`	string	이러한 조회에 대한 EUR 비용을 나타내는 십진수 값 문자열입니다.	false
`storage`	string	조회 결과가 추가된 스토리지(리포트)의 이름입니다. 이 이름은 웹 인터페이스를 통한 CSV 다운로드 및 분석에 사용됩니다.	false
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자 식별자입니다.	false
`webhook_urls`	array	API 설정에 구성된 웹훅 URL입니다. 결과는 여기로 전송됩니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

웹훅 처리

제출이 완료되면 플랫폼이 제공된 전화번호를 처리하기 시작하고, 결과를 귀하의 서버에 사전 지정된 웹훅 URL로 전송합니다. 결과는 요청 본문에 JSON 객체가 포함된 HTTP POST 요청으로 전송됩니다.

인증

X-Signatures HTTP 헤더를 검사하여 웹훅을 인증하세요.

X-Signatures 헤더에는 세미콜론으로 구분된 서명 목록이 포함되어 있습니다. 목록의 각 서명은 귀하의 계정에 구성된 API 시크릿 중 하나를 사용하여 생성됩니다. 웹훅을 검증하려면 API 키, 시크릿, 원시 HTTP 본문을 사용하여 SHA-256 해시를 생성한 다음, 목록의 서명과 비교하세요.

일치하는 경우 요청이 진본이며 귀하가 관리하는 시크릿으로 서명되었음을 확인합니다.

코드 예제

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

헤더에 제공된 서명 중 하나가 API 키, 시크릿, HTTP 본문을 연결한 문자열에 대해 계산된 SHA256 해시와 일치하면 요청이 유효합니다.

수신 확인

귀하의 서버는 성공적인 수신을 확인하기 위해 HTTP 상태 코드 200 OK로 응답해야 합니다. 다른 응답 코드가 반환되거나, 타임아웃이 발생하거나(10초), 기타 전송 문제가 발생하면 시스템은 1분 후 자동으로 웹훅을 재시도합니다. 요청이 계속 실패하면 지수 백오프 전략에 따라 재시도가 이루어지며, 이후 시도는 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024분 후에 진행됩니다.

이 재시도 메커니즘은 귀하의 인프라로 조회 결과를 전송하는 데 있어 최대한의 안정성을 보장합니다. 일시적인 네트워크 문제나 서버 다운타임으로 인한 데이터 손실 위험을 최소화합니다.

웹훅 페이로드

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

웹훅 페이로드 속성

JSON 객체는 type => NT 속성과 함께 아래 문서화된 조회 객체 목록을 포함하는 results 속성을 포함합니다.

이름	유형	설명	Null 허용
`id`	string(12)	이 조회 요청에 할당된 고유 식별자입니다.	false
`number`	string	이 조회 요청 중 평가된 전화번호입니다.	false
`number_type`	string	감지된 번호 유형입니다. 가능한 값: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN`	false
`query_status`	string	번호 유형 정보를 성공적으로 획득했는지 여부를 나타냅니다. 성공 시 `OK`를, 조회 실패 시 `FAILED`를 반환합니다.	false
`is_valid`	boolean	전화번호가 구문적으로 유효한지 여부를 나타냅니다.	true
`invalid_reason`	string	전화번호가 유효하지 않은 이유를 영문으로 설명하는 일반 텍스트 메시지입니다(예: "too short" 또는 "invalid prefix"). 번호가 유효한 경우 `null`을 반환합니다.	true
`is_possibly_ported`	boolean	전화번호가 원래 통신사에서 다른 통신사로 이동했을 가능성이 있는지 여부를 나타냅니다. 정확한 번호이동 정보는 MNP 조회를 이용하시기 바랍니다.	true
`is_vanity_number`	boolean	전화번호가 알파벳 문자를 포함하는 배니티 번호인지 여부를 나타냅니다.	true
`qualifies_for_hlr_lookup`	boolean	HLR 조회를 통한 추가 쿼리가 가능한 전화번호인지 여부를 나타냅니다.	true
`mccmnc`	string(5\|6)	휴대전화번호의 원래 네트워크를 식별하는 MCCMNC 튜플(이동통신 국가 코드 및 이동통신 네트워크 코드)을 나타내는 5자리 또는 6자리 문자열입니다.	true
`mcc`	string(3)	전화번호의 원래 이동통신 네트워크와 연결된 국가를 식별하는 MCC(이동통신 국가 코드)를 나타내는 3자리 문자열입니다.	true
`mnc`	string(2\|3)	전화번호의 원래 이동통신 네트워크 사업자를 식별하는 MNC(이동통신 네트워크 코드)를 나타내는 2자리 또는 3자리 문자열입니다.	true
`original_network_name`	string	조회된 휴대전화번호의 원래 네트워크 사업자 이름을 영문으로 지정하는 임의의 일반 텍스트 문자열입니다.	true
`original_country_name`	string	조회된 휴대전화번호와 연결된 원래 국가를 영문으로 지정하는 임의의 일반 텍스트 문자열입니다.	true
`original_country_code`	string(2)	조회된 휴대전화번호의 원래 국가를 나타내는 2자리 ISO 국가 코드입니다.	true
`regions`	array	이 전화번호와 연결된 지리적 지역을 영문으로 지정하는 사람이 읽을 수 있는 문자열 목록입니다.	true
`timezones`	array	이 전화번호와 연결된 시간대(Olson 형식) 목록입니다.	true
`info_text`	string	전화번호에 대한 추가 정보를 포함할 수 있는 임의의 문자열입니다.	true
`cost`	string	이 조회의 비용(EUR)을 나타내는 문자열 형식의 십진수 값입니다.	true
`timestamp`	string	조회가 완료된 시간을 나타내는 W3C 형식의 타임스탬프(시간대 포함)입니다.	true
`storage`	string	조회 결과가 추가된 저장소 이름을 지정합니다. 이는 웹 인터페이스를 통한 CSV 다운로드 및 분석에 사용되는 리포트 이름과 일치합니다.	true
`route`	string(3)	이 조회 요청에 사용된 경로를 지정하는 3자리 식별자입니다.	true

유형	설명
LANDLINE	유선 전화번호입니다.
MOBILE	이동전화번호입니다. HLR 조회를 통해 연결 상태, 네트워크, 번호이동성 및 로밍 정보를 확인할 수 있습니다.
MOBILE_OR_LANDLINE	유선 또는 이동전화번호입니다. HLR 조회가 가능할 수 있습니다.
TOLL_FREE	무료 전화번호입니다.
PREMIUM_RATE	추가 요금이 부과되는 프리미엄 요금 전화번호입니다.
SHARED_COST	공동 부담 전화번호입니다. 일반적으로 프리미엄 요금 전화번호보다 저렴합니다.
VOIP	인터넷 전화번호입니다. TSoIP 전화번호(IP 기반 전화 서비스)를 포함합니다.
PAGER	무선호출기 전화번호입니다. 일반적으로 음성 통화 기능이 없습니다.
UAN	통합 접속 번호(대표번호)입니다. 특정 사무실로 연결될 수 있지만 회사에서 하나의 번호를 사용할 수 있습니다.
VOICEMAIL	음성사서함 전화번호입니다.
UNKNOWN	번호 유형을 확인할 수 없습니다.

위로 스크롤

GET/route보호됨

route 매개변수를 지정하지 않고 HLR 조회를 실행할 때 자동으로 선택되는 경로를 조회합니다.

자동 경로 선택은 GET /hlr-coverage 엔드포인트로 조회 가능한 라우팅 맵을 기반으로 하며, 이는 주로 GET /routing-map에서 파생됩니다. 계정 설정에서 라우팅 맵을 사용자 지정하고 맞춤 규칙을 정의할 수 있습니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

요청 매개변수

키	유형	설명	기본값	필수
`msisdn`	string	자동 선택된 라우팅 정보를 조회할 MSISDN입니다.	null	필수

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

성공 응답 속성

이름	유형	설명	Null 허용
`route`	string	권장 경로입니다.	false
`confidence_level`	string	이 경로가 선택된 신뢰 수준, 즉 `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	이 번호의 번호 체계 기반 MCCMNC입니다.	false
`origin`	string	라우팅 결정의 기반이 되는 출처입니다 (예: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`)	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/routes보호됨

이 엔드포인트는 사용 가능한 HLR, MNP, NT 라우트 목록을 반환합니다. 각 라우트의 기능 및 제한 사항은 라우팅 세부 정보 페이지에서 확인하실 수 있습니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

성공 응답 속성

이름	유형	설명	Null 허용
`routes`	object	라우트 유형별로 그룹화된 라우트 객체입니다.	false
`HLR\|MNP\|NT`	string[]	라우트 식별자 목록을 포함합니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/routing-map보호됨

귀하의 계정에 현재 적용된 HLR 조회의 자동 라우팅 구성을 조회합니다. 이 기본 구성은 route 파라미터를 지정하지 않고 HLR 조회를 제출할 때마다 사용됩니다. 계정 설정에서 라우팅 맵을 사용자 정의하고 맞춤 규칙을 생성할 수 있습니다.

구성 계층은 국가 수준 규칙에서 MCCMNC 수준 규칙으로, 최종적으로 개별 전화번호 프리픽스 매핑으로 단계적으로 적용됩니다. 실제로 이는 개별 전화번호 프리픽스 매핑이 충돌하는 MCCMNC 할당보다 우선하며, MCCMNC 할당은 다시 국가 수준 규칙보다 우선함을 의미합니다. MNP 폴백이 활성화된 경우 충돌하는 모든 맞춤 규칙보다 우선 적용됩니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

성공 응답 속성

이름	유형	설명	Null 허용
`default_route`	string	MSISDN에 대해 선호하는 라우팅 옵션을 결정할 수 없고 맞춤 라우팅 규칙이 적용되지 않을 때 사용되는 기본 라우트입니다.	false
`mnp_fallback`	boolean	MNP 폴백 활성화 여부를 나타냅니다. 활성화된 경우 네트워크에서 HLR 쿼리를 지원하지 않으면(연결 상태 사용 불가) 시스템이 대신 MNP 조회를 수행합니다.	false
`mccmncs`	array	MCCMNC 코드와 자동으로 선택된 라우트의 매핑입니다. 특정 MCCMNC의 번호에 대해 HLR 조회를 수행할 때 해당 라우트가 사용됩니다.	false
`mccmnc`	string(5\|6)	이동통신사를 식별하는 5자리 또는 6자리 MCCMNC(이동통신 국가 코드와 이동통신망 코드 조합)입니다.	false
`countrycode`	string(2)	네트워크의 국가를 식별하는 두 자리 ISO 국가 코드입니다.	false
`route`	string(3)	네트워크에 대해 선택된 라우트입니다.	false
`mno`	string	이 통신망이 운영되는 소비자 대상 브랜드명입니다.	false
`confidence`	string	선택이 이루어진 신뢰도 수준입니다. 가능한 값: HIGH, NORMAL, LOW, MNP_REDIRECT. MNP_REDIRECT의 경우 이 동작이 계정에서 활성화되어 있으면 시스템이 해당 네트워크로의 트래픽을 MNP로 리디렉션합니다. 그렇지 않으면 계정의 기본 라우트를 사용합니다.	false
`origin`	string	선택의 기반이 되는 출처입니다. 가능한 값: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	계정에 구성된 맞춤 프리픽스 기반 라우팅 규칙 목록입니다(있는 경우).	false
`countrycode`	string(2)	프리픽스의 국가를 식별하는 두 자리 ISO 국가 코드입니다.	false
`cns`	string	라우팅 규칙이 적용되는 프리픽스입니다.	false
`route`	string(3)	프리픽스에 대해 선택된 라우트입니다.	false
`mccmnc`	string(5\|6)	이동통신사를 식별하는 5자리 또는 6자리 MCCMNC(이동통신 국가 코드와 이동통신망 코드 조합)입니다.	true
`mno`	string	이 통신망이 운영되는 소비자 대상 브랜드명입니다.	true
`countries`	array	계정에 구성된 맞춤 국가 기반 규칙 목록입니다(있는 경우).	false
`countrycode`	string(2)	국가를 식별하는 두 자리 ISO 국가 코드입니다.	false
`route`	string(3)	국가에 대해 선택된 라우트입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/hlr-coverage 보호됨

데이터 기반 의사결정을 지원하는 HLR 커버리지 인사이트를 제공합니다. 이 엔드포인트는 모바일 네트워크 전반의 실시간 HLR 라우팅 옵션을 분석하고, 대상 지역에 가장 효과적인 경로를 식별하며, 자동 라우팅을 구성하는 데 도움을 줍니다.

GET /route의 권장 경로는 여기에서 조회된 커버리지 데이터를 기반으로 합니다. 커버리지 데이터는 네트워크 커버리지 페이지에서도 확인할 수 있습니다. 계정 설정에서 라우팅 맵을 추가로 사용자 정의하고 규칙을 정의할 수 있습니다.

결과 해석에 도움이 되도록 이 가이드를 숙지하시기 바랍니다.

요청 성공 응답 오류 응답 상태 참조

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

요청 매개변수

키	유형	설명	기본값	필수
`countrycode`	string(2)	결과를 필터링하는 데 사용되는 필수 2자리 ISO 국가 코드로, 지정된 국가와 관련된 레코드만 반환합니다.	null	필수
`sample_size`	string	샘플 크기를 지정하는 선택적 매개변수입니다. 가능한 값은 `LARGE`, `MEDIUM`, `SMALL`입니다. 샘플이 클수록 더 긴 기간을 포함하며, 작을수록 최근 기간을 포함합니다.	LARGE	선택사항

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`name`	string	선택된 국가명(영문 텍스트).	false
`countrycode`	string(2)	선택된 국가의 2자리 ISO 국가 코드.	false
`prefix`	string	선택된 국가의 국제 전화 접두번호.	false
`mccs`	string[]	선택된 국가와 관련된 MCC(모바일 국가 코드) 목록.	false
`carriers`	object[]	경로별 연결성 메트릭이 포함된 통신사 객체 목록.	false
`mno`	string	이동통신사명(영문 텍스트).	false
`mccmnc`	string	이동통신사의 MCCMNC.	false
`mcc`	string	이동통신사의 MCC(모바일 국가 코드).	false
`mnc`	string	이동통신사의 MNC(모바일 네트워크 코드).	false
`routes`	object[]	경로별 연결성 결과 목록.	false
`route`	string	연결성 정보가 적용되는 경로.	false
`selected`	bool	자동 라우팅을 위해 선택된 경로인지 여부를 나타냅니다.	false
`selection_confidence`	string	이 경로가 선택된 신뢰 수준, 즉 `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. 선택된 경로가 아닌 경우 null을 포함합니다.	true
`n`	int	이 샘플의 총 조회 수.	false
`CONNECTED`	int	CONNECTED 상태를 반환한 HLR 조회 수.	false
`CONNECTED_PCT`	float	CONNECTED 상태를 반환한 HLR 조회 비율.	false
`ABSENT`	int	ABSENT 상태를 반환한 HLR 조회 수.	false
`ABSENT_PCT`	float	ABSENT 상태를 반환한 HLR 조회 비율.	false
`INVALID_MSISDN`	int	INVALID_MSISDN 상태를 반환한 HLR 조회 수.	false
`INVALID_MSISDN_PCT`	float	INVALID_MSISDN 상태를 반환한 HLR 조회 비율.	false
`UNDETERMINED`	int	UNDETERMINED 상태를 반환한 HLR 조회 수.	false
`UNDETERMINED_PCT`	float	UNDETERMINED 상태를 반환한 HLR 조회 비율.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

상태	설명
CONNECTED	유효한 번호이며, 대상 단말기가 현재 이동통신망에 연결되어 있습니다. 통화, SMS 및 기타 서비스가 수신자에게 정상적으로 전달됩니다.
ABSENT	유효한 번호이지만, 대상 단말기가 전원이 꺼져 있거나 일시적으로 네트워크 권역 밖에 있습니다. 단말기가 네트워크에 재연결될 때까지 메시지나 통화가 전달되지 않을 수 있습니다.
INVALID_MSISDN	유효하지 않은 번호이거나 현재 이동통신망의 가입자에게 할당되지 않은 번호입니다. 이 번호로의 통화 및 메시지 전송이 실패합니다.
UNDETERMINED	번호의 연결 상태를 확인할 수 없습니다. 이는 유효하지 않은 번호, SS7 오류 응답 또는 대상 네트워크 사업자와의 연결 부족으로 인한 것일 수 있습니다. 추가 진단을 위해 오류 코드 및 설명 필드를 확인하시기 바랍니다.

위로 스크롤

GET/mnp-coverage보호됨

이 엔드포인트는 현재 번호이동성 조회를 지원하는 이동통신사 목록과 해당 MCCMNC 식별자를 반환합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

요청 매개변수

키	유형	설명	기본값	필수
`countrycode`	string(2)	MCCMNC 결과를 필터링하는 데 사용되는 선택적 두 글자 ISO 국가 코드로, 지정된 국가와 관련된 데이터만 반환합니다.	null	선택사항

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

성공 응답 속성

이름	유형	설명	Null 허용
`items[]`	array	이동통신사 목록입니다.	false
`country_name`	string	영문 국가명입니다.	false
`country_code`	string(2)	두 글자 ISO 국가 코드입니다.	false
`mccmnc`	string(5\|6)	이동통신사를 식별하는 5자리 또는 6자리 MCCMNC(이동통신 국가 코드와 이동통신망 코드 조합)입니다.	false
`mcc`	string(3)	통신망의 국가를 나타내는 3자리 MCC(이동통신 국가 코드)입니다.	false
`mnc`	string(2\|3)	특정 이동통신사를 나타내는 2자리 또는 3자리 MNC(이동통신망 코드)입니다.	false
`brand`	string	이 통신망이 운영되는 소비자 대상 브랜드명입니다.	true
`operator`	string	이동통신사의 법적 명칭입니다.	true

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/price-list보호됨

이 엔드포인트는 MNP 조회만 지원되고 HLR 쿼리를 사용할 수 없는 국가 목록을 반환합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`countries`	string[]	두 자리 ISO 국가 코드 목록입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/mccmncs보호됨

이 엔드포인트는 MCCMNC 식별자 및 추가 컨텍스트 정보와 함께 이동통신사의 전체 목록을 반환합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

요청 매개변수

키	유형	설명	기본값	필수
`countrycode`	string(2)	MCCMNC 결과를 필터링하는 데 사용되는 선택적 두 글자 ISO 국가 코드로, 지정된 국가와 관련된 레코드만 반환합니다.	null	선택사항

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

성공 응답 속성

이름	유형	설명	Null 허용
`items`	object[]	이동통신사 목록입니다.	false
`country_name`	string	영문 전체 국가명입니다.	false
`country_code`	string(2)	이동통신사의 국가를 나타내는 두 글자 ISO 국가 코드입니다.	false
`mccmnc`	string(5\|6)	이동통신사를 고유하게 식별하는 5자리 또는 6자리 MCCMNC 문자열입니다.	false
`mcc`	string(3)	이동통신망이 운영되는 국가를 식별하는 3자리 이동통신 국가 코드(MCC)입니다.	false
`mnc`	string(2\|3)	주어진 MCC 내에서 이동통신망을 지정하는 2자리 또는 3자리 이동통신망 코드(MNC)입니다.	false
`brand`	string	네트워크가 운영되고 소비자에게 인식되는 상업적 브랜드명입니다.	true
`operator`	string	이동통신사의 공식 명칭으로, 일반적으로 네트워크를 관리하는 법인입니다.	true
`parent_mccmnc`	string(5\|6)	상위 이동통신사의 MCCMNC를 나타내는 5자리 또는 6자리 문자열입니다(해당하는 경우).	true

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/price보호됨

이 엔드포인트는 HLR, MNP 또는 NT 조회의 가격을 반환합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

요청 매개변수

키	유형	설명	기본값	필수
`msisdn`	string	가격을 조회할 전화번호입니다. 국제 형식으로 입력하세요.	null	필수
`route_type`	string	라우트 유형, 즉 `HLR`, `MNP`, `NT`입니다.	null	필수
`route`	string(3)	가격을 계산할 라우트입니다. 기본값은 자동 라우팅으로 결정된 라우트입니다.	null	선택사항

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

성공 응답 속성

이름	유형	설명	Null 허용
`price`	object	가격 정보를 포함한 객체입니다.	false
`amount`	string	EUR 단위의 금액입니다.	false
`msisdn`	string	이 가격이 적용되는 MSISDN입니다.	false
`route_type`	string(2\|3)	이 가격이 적용되는 라우트 유형입니다.	false
`route`	string(3)	이 가격이 적용되는 라우트입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/price-list보호됨

이 엔드포인트는 귀하의 계정에 적용되는 가격 정보를 반환합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

성공 응답 속성

이름	유형	설명	Null 허용
`pricing`	object[]	가격 정보가 포함된 객체 목록입니다.	false
`route`	string	해당 가격이 적용되는 라우트입니다.	false
`countrycode`	string	해당 라우트에 대해 이 가격이 적용되는 ISO 국가 코드(2자리)입니다(해당하는 경우).	true
`countryname`	string	국가 코드에 해당하는 영문 국가명입니다(해당하는 경우).	true
`mccmnc`	string	해당 라우트에 대해 이 가격이 적용되는 MCCMNC입니다(해당하는 경우). 국가 수준 가격보다 우선 적용됩니다.	true
`cns`	string	해당 라우트에 대해 이 가격이 적용되는 다이얼링 프리픽스입니다(해당하는 경우). 국가 수준 가격 및 MCCMNC 수준 가격보다 우선 적용됩니다.	true
`route_type`	string	해당 라우트 유형입니다(예: `HLR`, `MNP`, `NT`).	false
`route_type`	string	해당 가격(EUR)입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/balance보호됨

이 엔드포인트는 현재 계정 잔액을 조회하여 크레딧 상태에 따라 프로세스를 자동화할 수 있습니다. 결제 페이지에서 설정할 수 있는 잔액 부족 알림 이메일과 원활하게 연동됩니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

성공 응답 속성

이름	유형	설명	Null 허용
`balance`	string	EUR 단위의 현재 계정 잔액입니다. 문자열 형식의 소수점 값입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/ping공개

이 엔드포인트는 API에 핑 요청을 전송하여 HLR Lookups API 연결을 테스트할 수 있는 간단한 방법을 제공합니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

성공 응답 속성

이름	유형	설명	Null 허용
`success`	boolean	요청이 성공적으로 처리되었음을 나타냅니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/time공개

이 엔드포인트는 HLR Lookups 서버의 현재 시간을 나타내는 Unix 타임스탬프를 반환합니다. 인증을 위한 Digest-Auth 서명을 생성할 때 서버 시계를 동기화하는 데 사용하여, 귀하의 서버 시간과 HLR Lookups 서버 시간 간의 불일치를 수정할 수 있습니다.

요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

성공 응답 속성

이름	유형	설명	Null 허용
`time`	integer	현재 HLR Lookups 서버 시간을 나타내는 Unix 타임스탬프입니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

GET/auth-test보호됨

이 엔드포인트는 Basic-Auth 또는 권장되는 Digest-Auth 구현을 위한 초기 테스트로 사용됩니다.

Basic 인증 요청 Digest 인증 요청 성공 응답 오류 응답

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

요청 헤더

키	유형	설명
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`의 SHA256 해시. 해시에 콜론 기호(:)를 포함하세요.

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

요청 헤더

키	유형	설명
`X-Digest-Key`	string	HLR Lookups API 키
`X-Digest-Signature`	string	고유 Digest 인증 서명 (인증 참조)
`X-Digest-Timestamp`	integer	현재 Unix 타임스탬프 (`GET /time` 참조)

{
    "success":true
}

성공 응답 속성

이름	유형	설명	Null 허용
`success`	boolean	요청이 성공적으로 처리되었음을 나타냅니다.	false

{
    "errors":[
        "Service unavailable."
    ]
}

오류 응답 매개변수

이름	유형	설명	Null 허용
`errors[]`	string[]	오류를 설명하는 문자열 목록입니다.	false

위로 스크롤

레거시 API 문서

레거시 API는 더 이상 사용되지 않으며 향후 종료될 예정입니다. 가능한 한 빠른 시일 내에 최신 버전으로 업그레이드하실 것을 강력히 권장합니다.

2013년부터 2020년 초 사이에 HLR Lookups API를 구현하신 경우, 레거시 API를 사용하고 계십니다. 이 경우 레거시 API 문서를 참조하시기 바랍니다.

레거시 API 문서

API 문서

시작하기

HLR 조회

MNP 조회

NT 조회

라우팅

요금제

도구

시작하기

HLR Lookups API 사용하기

요청 예시

페이로드 예시

성공 응답 application/json

추가 조회 서비스

번호 이동성(MNP) 조회

번호 유형 탐지(NT) 조회

소프트웨어 개발 키트(SDK)

도구

개발자가 아니신가요?

인증

API 키 및 API 시크릿

HTTP Basic 인증

권장: SHA256을 사용한 X-Basic 헤더

Basic 인증 요청

Basic 인증 헤더

코드 예제

요청 예제

요청 헤더

서명 생성

Digest 서명 구성 요소

코드 예제

개념

동기식 HLR 조회 API

비동기 HLR 조회 API

SDK (소프트웨어 개발 키트)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookup보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수

POST/hlr-lookups보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수

웹훅 처리

인증

코드 예제

수신 확인

웹훅 페이로드

웹훅 페이로드 속성

POST/mnp-lookup보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수

POST/mnp-lookups보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수

웹훅 처리

인증

코드 예제

수신 확인

웹훅 페이로드

웹훅 페이로드 속성

POST/nt-lookup보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수

POST/nt-lookups 보호됨

페이로드

요청 매개변수

성공 응답 속성

오류 응답 매개변수