{"openapi":"3.0.3","info":{"title":"APICK 전화번호 유효성 검사","version":"1.0.0","description":"전화번호의 형식 유효성을 검사하고, 통신사·회선유형까지 함께 조회합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/check_phone_valid":{"post":{"summary":"전화번호 유효성 검사","description":"전화번호의 형식 유효성을 검사하고, 통신사·회선유형까지 함께 조회합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"국제번호":{"type":"string","description":"국제 표기 번호입니다. 예: +821012345678. 번호로 인식하지 못하면 null입니다.","nullable":true},"지역번호":{"type":"string","description":"그 나라의 국내 표기 번호입니다. 예: 010-1234-5678. 화면 표시용으로 쓰기 좋습니다.","nullable":true},"유효성":{"type":"boolean","description":"국가별 번호 체계상 형식이 맞는지 여부입니다. 형식만 보는 값이므로, 지금 개통된 번호인지는 hlr.활성회선여부로 확인하세요."},"국가":{"type":"string","description":"번호가 속한 국가 이름(영문)입니다. 예: South Korea"},"지역":{"type":"string","description":"번호가 속한 지역 이름입니다. 현재는 국가 이름과 같은 값입니다."},"국가코드":{"type":"string","description":"국가를 구분하는 영문 2자리 코드입니다. 예: KR, US"},"모바일여부":{"type":"boolean","description":"번호 형식상 휴대전화 번호인지 여부입니다."},"회선유형":{"type":"string","description":"번호 형식상 회선 유형입니다. mobile(휴대전화) 또는 fixed-line(그 외)입니다."},"hlr":{"type":"object","properties":{"활성회선여부":{"type":"boolean","description":"지금 개통돼 통화·문자를 받을 수 있는 회선이면 true, 아니면 false입니다. 상태를 확인할 수 없는 경우(상태코드가 unavailable·failed)는 null입니다.","nullable":true},"개통상태":{"type":"string","description":"상태코드의 한글 이름입니다. 개통 / 부재 / 결번/미개통 / 유효하지 않은 번호 / 유선 / VOIP / 제공되지 않음 / 조회실패 중 하나입니다."},"상태코드":{"type":"string","description":"회선 상태 코드입니다.ok: 개통(사용 중)absent: 부재(개통됐지만 지금 연결되지 않음)unknown: 결번 또는 미개통invalid: 유효하지 않은 번호fixed-line: 유선 번호voip: 인터넷 전화 번호unavailable: 이 번호는 회선 상태를 제공하지 않음failed: 회선 상태를 받지 못함"},"HLR유효":{"type":"boolean","description":"회선 상태를 확인했는지 여부입니다. 상태코드가 unavailable·failed이면 false입니다."},"번호유효":{"type":"boolean","description":"회선 조회 기준으로 유효한 번호인지 여부입니다."},"모바일여부":{"type":"boolean","description":"회선 조회 기준 휴대전화 여부입니다. 회선 유형을 모르면 null입니다.","nullable":true},"번호이동여부":{"nullable":true,"type":"boolean","description":"번호이동 여부입니다. 제공되지 않으면 null입니다."},"로밍여부":{"nullable":true,"type":"boolean","description":"로밍 중인지 여부입니다. 제공되지 않으면 null입니다."},"현재통신사":{"type":"string","description":"지금 이 번호를 쓰고 있는 통신사 이름입니다. 번호이동을 했다면 옮긴 뒤의 통신사입니다. 예: KT. 확인하지 못하면 null입니다.","nullable":true},"원통신사":{"nullable":true,"type":"string","description":"번호를 처음 개통한 통신사입니다. 제공되지 않으면 null입니다."},"이동통신사":{"nullable":true,"type":"string","description":"이동통신사 이름입니다. 제공되지 않으면 null이며, 통신사는 현재통신사를 쓰세요."},"회선유형":{"type":"string","description":"회선 조회 기준 유형입니다. mobile / fixed-line / voip / null","nullable":true},"위치":{"type":"string","description":"회선이 속한 국가 이름(영문)입니다.","nullable":true},"국가":{"type":"string","description":"회선이 속한 국가 이름(영문)입니다.","nullable":true},"국가코드":{"type":"string","description":"회선이 속한 국가의 영문 2자리 코드입니다.","nullable":true},"국제번호":{"type":"string","description":"회선 조회 기준 국제 표기 번호입니다.","nullable":true},"지역번호":{"type":"string","description":"회선 조회 기준 국내 표기 번호입니다.","nullable":true},"도달가능성":{"type":"string","description":"회선 도달 상태 원값입니다. active / reachable / unreachable / inactive / null. 판단은 상태코드로 하는 것이 간단합니다.","nullable":true},"MCC":{"type":"string","description":"이동통신 국가 코드입니다. 휴대전화 번호에만 있습니다. 예: 450(대한민국)","nullable":true},"MNC":{"type":"string","description":"이동통신 사업자 코드입니다. 휴대전화 번호에만 있습니다.","nullable":true}},"description":"회선 조회 결과입니다. 번호가 지금 개통돼 있는지와 현재 통신사를 담습니다."},"success":{"type":"integer","description":"처리 상태입니다. 1이면 검사가 끝난 정상 응답(요금 차감), 0이면 실패 응답(차감 없음)입니다."},"error":{"type":"string","description":"실패 사유 문구입니다. 정상 응답에는 없으며, 값이 있으면 아래 오류 응답 표에서 원인과 조치를 확인하세요."}},"description":"검사 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다."},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"요청을 정상적으로 받아 처리했는지 여부입니다. 번호 상태는 data.유효성과 data.hlr로 확인하세요."},"cost":{"type":"integer","description":"이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다."},"ms":{"type":"integer","description":"요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다."},"pl_id":{"type":"integer","description":"포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있으며 과금 문의 때 사용합니다."}},"description":"호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다."}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"검증할 전화번호입니다. 국내는 하이픈 없이 숫자만(예: 01012341234), 해외는 +국가코드로 시작하는 형식을 사용합니다. (string)","example":"01012345678"}},"required":["number"]}}}}}}},"x-code-tables":[{"title":"오류 응답","columns":["HTTP","data.error","원인·조치"],"rows":[["400","입력 항목이 잘못됐습니다.","number가 없거나 빈 값입니다."],["424","HLR 조회에 실패했습니다.","회선 조회를 끝내지 못했습니다. 잠시 후 다시 요청하세요."],["424","HLR 서비스는 대량 이용 시 사전 문의가 필요합니다. 문의를 남겨주세요.","이용 한도를 넘었습니다. 대량으로 쓰려면 고객지원으로 먼저 문의하세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}