# API v2를 사용한 전화 검증 및 포맷

> GenderAPI v2를 사용하여 국제 또는 국내 전화번호를 확인하고 형식을 지정하세요. 필수 국가 컨텍스트, JSON 필드 및 1크레딧 요금을 확인하세요.

Canonical HTML: https://www.genderapi.io/ko/docs/v2/phone-validation

Last reviewed: 2026-09-25

## 전화번호 확인 및 형식 지정

POST /phone/validate는 number 및 선택적 country 필드를 허용합니다. +로 시작하는 국제전화번호를 사용하세요. 국내 전화번호의 경우 대문자 ISO 국가 코드를 제공하세요. 응답에는 data 내부에 valid, possible, e164, country 및 country_calling_code와 공유 meta 개체가 있습니다. 이는 가입자 존재 여부가 아닌 전화번호의 구조를 확인하는 것입니다. 유효하지 않은 결과를 포함하여 완료된 각 검증 비용은 1크레딧입니다. 아래 예시 응답은 잘못된 숫자를 표시하며 요청 예시와 무관합니다.

서버에서 다음 예제를 실행하세요. 프로세스 환경에서 GENDERAPI_API_KEY를 기존 API 키로 설정합니다. meta.access.mode가 api_key인지 확인하세요. 인식되지 않은 키는 IP 평가판으로 대체될 수 있습니다.

모든 예측 요청은 재시도를 포함하여 청구 가능한 새로운 작업입니다. 이러한 예제는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 청구 상태를 확인하세요.

HTTP 4xx 및 5xx JSON 응답은 오류 본문을 보존하고 0이 아닌 종료 상태를 반환합니다. 다시 시도하기 전에 code, action 및 meta.usage.billing_status를 확인하세요.

| JSON 필드 | 유형 | 규칙 |
| --- | --- | --- |
| number | string | 필수, 3~32자. ASCII 숫자, 공백, 괄호 및 하이픈(선택 사항으로 앞에 +가 있음). 확장자 및 알파벳 문자는 허용되지 않습니다. |
| country | string | 대문자 ISO 3166-1 alpha-2 코드입니다. 국내 전화번호에 필요합니다. number 값이 +로 시작하는 경우 선택 사항입니다. 필요하지 않은 경우 이 필드를 생략하세요. |

**cURL**

POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요.

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/phone/validate' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "number": "+905321234567"
}'
```

**JavaScript / Node.js**

Node.js 22+; 내장된 가져오기. example.mjs로 저장하고 node example.mjs를 실행합니다.

```javascript
// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "number": "+905321234567"
};

const response = await fetch("https://api.genderapi.io/api/v2/phone/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}
```

**Python**

Python 3.10+; 표준 라이브러리. example.py로 저장하고 python3 example.py를 실행합니다.

```python
import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"number\":\"+905321234567\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/phone/validate",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.
```

**PHP**

PHP 8+(cURL 확장 포함). example.php로 저장하고 php example.php를 실행합니다.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"number":"+905321234567"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/phone/validate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.
```

**Java**

Java 17+; 표준 HTTP 클라이언트. GenderApiExample.java로 저장하고 java GenderApiExample.java를 실행합니다.

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"number\":\"+905321234567\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/phone/validate"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}
```

**C# / .NET**

.NET 8+ 콘솔 애플리케이션. 콘솔 프로젝트에서 Program.cs로 사용한 후 dotnet run를 실행하세요.

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/phone/validate");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"number\":\"+905321234567\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}
```

**Go**

Go 1.22+; 표준 라이브러리. main.go로 저장하고 go run main.go를 실행합니다.

```go
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"number\":\"+905321234567\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/phone/validate", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}
```

```json
{
  "data": {
    "valid": false,
    "possible": false,
    "e164": null,
    "country": null,
    "country_calling_code": null
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 7,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## 전화 확인 필드 읽기

잘못된 입력은 청구 전에 HTTP 422로 거부됩니다. 요청 형식은 정확하지만 전화번호를 구문 분석할 수 없는 경우 작업은 valid: false 및 null 형식 필드와 함께 HTTP 200을 반환할 수 있습니다. 완료된 검증 비용은 1크레딧입니다. 구문 분석할 수 있지만 유효하지 않은 숫자에도 여전히 e164 값이 있을 수 있습니다. valid를 확인하세요. 형식이 지정된 숫자만으로는 유효성을 증명할 수 없습니다.

| data 내부 필드 | 의미 |
| --- | --- |
| valid | 번호가 번호 매기기 계획 유효성 검사 규칙과 일치하는지 여부입니다. |
| possible | 번호 매기기 계획에 적합한 길이가 있는지 여부 유효한 것보다 약합니다. |
| e164 | 구문 분석이 성공하면 국제 형식의 숫자이고, 그렇지 않으면 null입니다. |
| country | 사용할 수 없는 경우 번호 또는 null에서 파생된 지역입니다. 가입자를 찾지 않습니다. |
| country_calling_code | 숫자로 된 국제 전화 코드 또는 사용할 수 없는 경우 null. |

## 인증 및 재시도

Bearer 인증 및 Content-Type: application/json을 사용하여 기존 API 키를 보냅니다. 예제에서는 환경에서 GENDERAPI_API_KEY를 읽습니다. country 필드는 국내 전화번호에 필수이며 number 값이 +로 시작하는 경우 선택 사항입니다.

- [인증](https://www.genderapi.io/ko/docs/v2/authentication)
- [오류 및 재시도](https://www.genderapi.io/ko/docs/v2/errors-and-retries)
- [크레딧 및 사용량](https://www.genderapi.io/ko/docs/v2/credits-and-usage)