개발자 플랫폼

Temp Number API - 전화번호, SMS 및 OTP

가상 전화번호를 발급하고, SMS를 실시간으로 수신하고, OTP 인증을 자동화하세요. 깔끔한 REST API로, 또는 AI 어시스턴트에서 바로 사용할 수 있습니다.

REST · JSON AI 에이전트용 MCP cURL · Node.js · Python · PHP
BASE URL https://api.temp-number.com/v1

홈 / 개발자

소개

Temp Number API는 예측 가능한 리소스 구조로 구성되어 있고, 표준 HTTP 메서드를 사용하며, 모든 응답을 JSON으로 반환합니다. 하나의 키로 본인 계정에만 읽기 및 쓰기 권한이 부여되며, 다른 계정에는 접근할 수 없습니다.

프로토콜HTTPS · JSON
인증Bearer 키
버전v1 (안정 버전)
엔드포인트17개 운영 중

빠른 시작

처음부터 인증 코드 수신까지. 언어를 한 번만 선택하면 페이지의 모든 예제가 그 언어로 표시됩니다.

  1. API 키 만들기

    대시보드 → API 액세스에서 키를 만드세요. 키는 한 번만 표시되므로 환경 변수 TEMP_NUMBER_API_KEY에 저장하세요.

  2. 잔액 확인

    모든 호출은 Authorization 헤더에 키를 담아 보냅니다. 지갑 잔액 조회처럼 부담 없는 호출부터 시작해 보세요.

    curl --request GET "https://api.temp-number.com/v1/account" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  3. 국가 선택 및 재고 확인

    GET /pricing은 모든 국가와 기간별 정확한 가격을 보여 줍니다. 그다음 원하는 국가의 재고를 확인하세요.

    curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  4. 번호 구매

    구매할 때마다 새 Idempotency-Key를 보내세요. 네트워크가 끊기면 같은 키로 재시도하면 되며, 이중 결제는 절대 발생하지 않습니다. 응답의 data.id를 보관하세요.

    curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json" \
      --header "Idempotency-Key: $(uuidgen)" \
      --data '{"country_code":"US","duration":"oneMonth"}'
  5. SMS 읽기

    메시지가 도착할 때까지 몇 초마다 번호를 폴링하세요. 원본 텍스트가 전달되므로 코드는 직접 추출하세요.

    curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  6. SMS가 안 오나요? 취소하고 환불받기

    구매 후 15분에서 120분 사이에 SMS를 받지 않은 번호는 취소하고 지갑으로 전액 환불받을 수 있습니다.

    curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Idempotency-Key: $(uuidgen)"

인증

모든 요청에서 표준 Authorization 헤더에 API 키를 담아 보내세요:

http
Authorization: Bearer YOUR_API_KEY
  • API 액세스에서 키를 만드세요. 키 전체는 생성 시 한 번만 표시됩니다.
  • 연동마다 키를 하나씩 사용하면 다른 연동에 영향을 주지 않고 하나만 폐기할 수 있습니다. 비밀번호를 변경하면 모든 키가 폐기됩니다.
  • 키가 없거나, 형식이 잘못되었거나, 폐기된 경우 401을 반환합니다. 이메일 인증을 완료하지 않았거나 정지된 계정은 403과 함께 code email_unverified 또는 account_suspended를 반환합니다.
  • REST 키는 /v1에서만 작동합니다. MCP 서버는 자체 로그인 또는 MCP 키를 사용합니다. MCP 서버를 참고하세요.
키는 비밀번호처럼 관리하세요. 키는 서버에만 보관하고 웹 페이지나 모바일 앱에 넣지 마세요. 로그에 남았거나 커밋되었거나 공유된 적이 있다면 즉시 교체하세요.

기본 URL 및 버전 관리

모든 엔드포인트는 고정된 /v1 접두사 아래에 있습니다:

기본 URL
https://api.temp-number.com/v1

새 필드, 엔드포인트, 선택적 매개변수 같은 추가형 변경은 버전 변경 없이 배포되므로 알 수 없는 필드는 무시하세요. 호환성을 깨는 변경은 /v2로 배포되며, 연동이 예고 없이 이전되는 일은 없습니다. 기계가 읽을 수 있는 명세는 OpenAPI 스펙입니다.

요청 및 응답

  • 모든 요청에 JSON 본문은 Content-Type: application/json으로 보내고 Accept: application/json을 포함하세요.
  • 성공: { "success": true, "data": …, "meta": {…} }. meta에는 개수, 페이지네이션, 금액 요약이 담깁니다.
  • 오류: { "success": false, "message": "…", "code": "…" }. 분기 처리는 code로 하세요. 메시지는 사람이 읽기 위한 것입니다. 오류를 참고하세요.
  • 시간은 ISO 8601 형식입니다. 금액은 소수점 둘째 자리까지의 USD이며, 항상 실제로 결제하는 가격입니다.
  • 일부 객체에는 기존 연동을 위해 이전 필드 이름이 남아 있습니다(레퍼런스에 deprecated로 표시). 새 코드에서는 이를 무시하세요.
응답에는 업스트림 제공업체 이름이나 도매 원가가 표시되지 않습니다. 표시되는 가격은 지갑에서 청구되는 금액뿐이므로 고객에게 그대로 보여 줘도 안전합니다.

오류

오류는 표준 HTTP 상태 코드를 사용합니다. 비즈니스 오류에는 안정적이고 기계가 읽을 수 있는 code가 포함되며, 일부는 추가 정보를 담은 details를 포함합니다.

422 · 비즈니스 오류
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · 유효성 검사 오류
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
상태code의미해야 할 일
400 - 구매, 갱신 또는 취소 요청에 Idempotency-Key 헤더가 없거나 형식이 잘못되었습니다. 본문: {"error": "Missing Idempotency-Key header."} Idempotency-Key에 UUID를 보내세요.
401 - Bearer 토큰이 없거나 형식이 잘못되었거나 폐기된 키입니다. Authorization 헤더를 확인하세요. 키가 폐기되었다면 새 키를 만드세요.
403 email_unverified 계정의 이메일 주소가 아직 인증되지 않았습니다. 웹사이트에서 이메일을 인증한 후 다시 시도하세요.
403 account_suspended 계정이 정지되었습니다. 고객 지원팀에 문의하세요.
403 kyc_required 새 번호를 구매하려면 계정 본인 인증이 필요합니다. 요금은 청구되지 않았으며 갱신은 계속 가능합니다. 계정 설정에서 본인 인증을 완료한 후 다시 시도하세요.
403 - 키에 API 접근 권한이 없거나(예: MCP 키), GET /receive-sms로 다른 계정의 번호를 조회했습니다. REST API 키를 사용하고, 본인 번호만 조회하세요.
404 - 번호, 메시지 또는 국가가 계정에 없거나 현재 판매 중이 아닙니다. 다른 계정의 id도 404를 반환합니다. GET /numbers 또는 GET /pricing으로 다시 조회하세요.
404 private_email_closed 번호가 취소 또는 환불되어 비공개 받은편지함이 종료되었습니다. 재시도할 필요가 없습니다.
409 - Idempotency-Key가 다른 본문으로 이미 사용되었거나, 해당 키를 사용한 첫 요청이 아직 처리 중입니다. 새 요청에는 새 키를 사용하고, 처리 중인 요청은 기다렸다가 재시도하세요.
422 insufficient_funds 지갑 잔액이 가격보다 부족합니다. 지갑을 충전한 후 다시 시도하세요.
422 out_of_stock 가격 확인과 구매 사이에 품절되었습니다. GET /inventory를 다시 확인하고 다른 기간이나 유형을 선택하세요.
422 invalid_duration 해당 국가와 번호 유형에서는 판매하지 않는 기간입니다. GET /pricing/{countryCode}를 다시 조회하세요.
422 - 유효성 검사에 실패했거나(`errors` 객체에 각 필드 표시) 환불 가능 기간 외 취소처럼 규칙에 의해 작업이 거부되었습니다. `message`를 읽고, 재시도하기보다 요청을 수정하세요.
429 - 요청 한도에 도달했습니다. Retry-After 헤더만큼 기다린 후 백오프를 적용해 재시도하세요.
503 purchases_paused 플랫폼 전체에서 신규 구매가 일시 중지되었습니다. 요금은 청구되지 않았으며 갱신과 취소는 계속 가능합니다. Retry-After(60초) 후에 재시도하세요.
5xx - 서버 측에서 문제가 발생했습니다. 같은 Idempotency-Key로 재시도하세요 - 이중 결제는 절대 발생하지 않습니다.

요청 한도

한도는 키별로 적용되며, 결제가 발생하는 호출에는 계정별로 더 엄격한 한도가 추가로 적용됩니다:

적용 대상한도집계 대상
전체 엔드포인트분당 60회API 키당
구매, 갱신, 취소분당 10회계정당(위 제한에 추가로 적용)
GET /receive-sms분당 60회API 키당
GET /receive-sms분당 30회API 키 및 전화번호당
GET /receive-sms분당 30회IP 주소당

한도를 초과하면 Retry-After 헤더(초 단위)와 함께 429가 반환됩니다. 최소 그 시간만큼 기다린 후 지터를 적용해 백오프하세요. 응답에는 X-RateLimit-Limit와 X-RateLimit-Remaining도 포함됩니다.

SMS를 기다리고 계신가요? 한 번호에 대한 폴링은 최대 5초에 한 번으로 제한하세요.

멱등성

POST /numbers/buy, /renew, /cancel에는 Idempotency-Key 헤더가 필수입니다. 새 작업마다 직접 생성한 UUID를 사용하세요. 네트워크가 끊기면 같은 키로 같은 요청을 다시 보내세요. 원래 응답이 반환되며(X-Idempotency-Replayed: true 표시) 요금이 두 번 청구되지 않습니다.

  • 키 누락: 400. 키는 최대 128자이며 영문자, 숫자, - _ . :를 사용할 수 있습니다
  • 같은 키로 다른 본문을 보내면 409가 반환됩니다. 첫 요청이 아직 처리 중일 때 같은 키를 보내도 409가 반환되니 잠시 후 다시 시도하세요.
  • 키는 계정과 엔드포인트별로 기억됩니다. 다른 구매에 같은 키를 재사용하지 마세요.

페이지네이션

GET /receive-sms는 최신순 커서 페이지네이션을 사용합니다. meta.hasMore를 확인하고, 값이 true인 동안 meta.nextCursor를 같은 phoneNumber와 함께 cursor로 다시 보내세요. 커서는 불투명한 값이므로 직접 만들거나 수정하지 마세요.

다음 페이지
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9

원래 크기가 작은 목록(/numbers, /pricing)은 한 번의 응답으로 모두 반환되며, 개인 수신함은 page와 per_page를 사용합니다.

허용되는 사용

이 API는 개발자를 위해 만들어졌습니다. 인증 및 OTP 흐름, 자동화된 온보딩, QA 및 시스템 테스트, 그리고 대규모로 수신 SMS나 전화번호가 필요한 모든 제품에 적합합니다.

  • 정당한 인증, 개발 및 테스트 용도로만 사용하세요.
  • 사기, 스팸, 기만 행위는 금지됩니다. 사기나 기타 악용 행위에 번호를 사용하면 계정이 사전 통보 없이 즉시 정지되고, 관련 번호가 취소되며, 환불되지 않습니다.
  • 규제 대상 또는 신원 확인이 필요한 계정에는 사용할 수 없습니다. 당사의 공유 임시 번호는 은행, 결제, 암호화폐, 정부 기관 등 법적 신원을 확인하는(KYC/AML) 서비스의 SMS 인증을 지원하지 않습니다. 이러한 서비스에는 본인의 휴대폰 번호를 사용하세요.
당사는 악용 여부를 모니터링합니다. 전체 조건은 서비스 약관에서 확인하세요.

API 레퍼런스

운영 중인 모든 /v1 엔드포인트입니다. 요청은 오른쪽에 선택한 언어로 표시되며, 응답은 실제 형식입니다.

계정

지갑 잔액과 정산 통화를 조회합니다.

GET /v1/account

계정 잔액 조회

사용 가능한 지갑 잔액과 통화를 반환합니다. 구매 전에 확인하면 "충전 필요" 메시지를 명확히 보여 주고 미리 중단할 수 있습니다.

응답 필드
  • balancenumber

    사용 가능한 지갑 잔액.

  • currencystring

    정산 통화, USD.

오류
  • 401키가 없거나 올바르지 않습니다.
curl --request GET "https://api.temp-number.com/v1/account" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "balance": 124.50,
  "currency": "USD"
}

가격 및 재고

판매 중인 국가, 기간별 정확한 결제 가격, 실시간 재고를 확인하세요.

국가별 가격 객체

한 국가와 그 국가에서 구매할 수 있는 모든 패키지. price는 지갑에서 결제되는 최종 금액이며, 원가는 공개되지 않습니다.

필드
  • country_codestring

    ISO 3166-1 alpha-2 코드, 예: US.

  • country_namestring

    표시 이름.

  • packages[].number_typeenum

    voip 또는 non_voip.

  • packages[].durationenum

    구매 시 보내는 키: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths, oneYear. 국가마다 제공하는 기간이 다릅니다.

  • packages[].duration_labelstring

    사람이 읽는 라벨, 예: "1개월".

  • packages[].pricenumber

    USD 기준 최종 가격.

  • packages[].original_pricenumber | null

    할인이 적용될 때 할인 전 가격.

  • packages[].updated_atnull

    예약됨.

객체
{
  "country_code": "US",
  "country_name": "United States",
  "packages": [
    {
      "number_type": "voip",
      "duration": "oneMonth",
      "duration_label": "1 Month",
      "price": 4.99,
      "original_price": 5.99,
      "updated_at": null
    }
  ]
}
GET /v1/pricing

전체 국가 가격 목록

전체 실시간 카탈로그: 국가별 가격 객체 목록. price 필드는 사용자에게 적용되는 USD 최종 요금으로, 지갑에서 결제되는 금액과 정확히 같습니다.

반환값

data에 국가별 가격 객체 목록, meta.count 포함.

오류
  • 401키가 없거나 올바르지 않습니다.
curl --request GET "https://api.temp-number.com/v1/pricing" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": [
    {
      "country_code": "US",
      "country_name": "United States",
      "packages": [
        {
          "number_type": "voip",
          "duration": "oneMonth",
          "duration_label": "1 Month",
          "price": 4.99,
          "original_price": 5.99,
          "updated_at": null
        },
        {
          "number_type": "voip",
          "duration": "threeMonths",
          "duration_label": "3 Months",
          "price": 12.99,
          "original_price": null,
          "updated_at": null
        }
      ]
    }
  ],
  "meta": { "count": 1 }
}
GET /v1/pricing/{countryCode}

한 국가의 가격 조회

한 국가의 실시간 가격. 404는 현재 해당 국가에 활성 경로가 없다는 뜻이므로 "판매하지 않음"이 아니라 일시적인 "품절"로 처리하세요.

매개변수
  • countryCode string path 필수

    ISO 3166-1 alpha-2 국가 코드, 예: US, GB, CA.

반환값

data에 국가별 가격 객체 하나.

오류
  • 404현재 해당 국가에 활성 경로가 없습니다.
curl --request GET "https://api.temp-number.com/v1/pricing/GB" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "packages": [
      {
        "number_type": "voip",
        "duration": "oneMonth",
        "duration_label": "1 Month",
        "price": 5.49,
        "original_price": null,
        "updated_at": null
      }
    ]
  }
}
GET /v1/inventory

재고 확인

국가와 기간별 실시간 재고를 확인해, 누군가 클릭하기 전에 구매 버튼을 비활성화할 수 있습니다. number_type을 생략하면 types[]에서 모든 유형을 나란히 볼 수 있습니다. 재고 있음 결과는 신뢰할 만한 신호지만, 최종 확인은 실제 구매 시점에 이루어집니다.

매개변수
  • country_code string query 필수

    ISO 3166-1 alpha-2 국가 코드.

  • duration enum query 선택 사항

    GET /pricing/{countryCode}의 기간 키. 생략하면 경로 기본값을 사용합니다.

    다음 중 하나 halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query 선택 사항

    한 유형으로 확인을 제한합니다. 모든 유형을 보려면 생략하세요.

    다음 중 하나 voipnon_voip
응답 필드
  • stockinteger | null

    구매 가능한 번호 수(number_type을 생략하면 types[] 합계).

  • availableboolean

    구매 가능한 번호가 하나 이상 있으면 true.

  • statusstring

    사람이 읽는 라벨: 재고 있음, 품절, 출시 예정…

  • types[]array

    number_type을 생략한 경우에만: 해당 시장에서 판매하는 유형별 number_type, stock, available, status.

오류
  • 422선택한 조건으로 판매 중인 상품이 없습니다. details에 재고 필드가 포함됩니다.
curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "country_code": "US",
    "duration": "oneMonth",
    "number_type": null,
    "stock": 47,
    "available": true,
    "status": "In Stock",
    "types": [
      { "number_type": "voip", "stock": 0, "available": false, "status": "Out of Stock" },
      { "number_type": "non_voip", "stock": 47, "available": true, "status": "In Stock" }
    ]
  }
}

번호

비공개 번호를 조회, 구매, 갱신, 취소하세요. 금액이 오가는 호출은 멱등성을 보장하며 재전송해도 안전합니다.

번호 객체

계정에 있는 번호. 구매, 갱신, 취소 시에는 meta에 금액 요약(charged 또는 refunded, currency, wallet_balance_after)도 반환됩니다.

필드
  • idinteger

    /numbers/{id}/… 호출에 사용합니다. Webhook에서는 number.rentalId로 전송됩니다.

  • phone_numberstring

    E.164 형식, 예: +14035551234.

  • country_codestring | null

    ISO 3166-1 alpha-2.

  • country_namestring

    표시 이름.

  • number_typeenum

    voip 또는 non_voip.

  • statusenum

    active, expired, cancelled 또는 refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 8601, UTC. 이 시점 이후로는 번호가 SMS를 받지 않으며 갱신할 수 없습니다.

이전 연동을 위해 계속 전송되는 지원 중단 별칭: country, provider, purchased_at, expires_at(에포크 밀리초). 새로 개발할 때는 사용하지 마세요.

객체
{
  "id": 1482,
  "phone_number": "+14035551234",
  "country_code": "US",
  "country_name": "United States",
  "number_type": "voip",
  "status": "active",
  "purchase_date": "2026-05-13T17:42:09Z",
  "expire_date": "2026-06-13T17:42:09Z"
}
GET /v1/numbers

내 번호 목록

계정의 모든 번호를 최신순으로 보여 줍니다. status=expiring_soon(만료 10일 이내의 활성 번호)을 사용해 갱신 알림을 보낼 수 있습니다.

매개변수
  • status enum query 선택 사항

    수명 주기 필터. 기본값 all.

    다음 중 하나 allactiveexpiring_soonexpiredcancelled
반환값

data에 번호 객체 목록, meta.count 및 meta.status 포함.

오류
  • 401키가 없거나 올바르지 않습니다.
curl --request GET "https://api.temp-number.com/v1/numbers?status=expiring_soon" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": [
    {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    }
  ],
  "meta": { "count": 1, "status": "expiring_soon" }
}
POST /v1/numbers/buy Idempotency-Key 필수

번호 구매

새 비공개 번호를 할당하고 지갑에서 결제하는 과정을 하나의 원자적 단계로 처리합니다. 결제 후 처리에 실패하면 결제가 취소되므로, 돈만 나가고 번호를 받지 못하는 일은 없습니다. 응답에는 결제 금액과 결제 후 잔액이 표시됩니다.

매개변수
  • country_code string body 필수

    GET /pricing에 있는 국가.

  • duration enum body 필수

    해당 국가 packages[]의 기간 키 - 국가마다 제공하는 기간이 다릅니다.

    다음 중 하나 halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body 선택 사항

    생략하면 경로 기본값을 사용합니다.

    다음 중 하나 voipnon_voip
  • Idempotency-Key string header 필수

    구매마다 새로 만들고, 재시도할 때는 그대로 다시 쓰는 UUID.

반환값

data에 새 번호 객체, meta.charged, meta.currency, meta.wallet_balance_after 포함.

오류
  • 422insufficient_funds지갑 잔액이 가격보다 부족합니다.
  • 422out_of_stock재고 확인 이후 품절되었습니다.
  • 422invalid_duration이 국가/유형에서는 판매하지 않는 기간입니다.
  • 403kyc_required먼저 본인 인증이 필요합니다. 요금은 청구되지 않았습니다.
  • 503purchases_paused플랫폼 전체에서 구매가 일시 중지되었습니다. Retry-After: 60.
curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"country_code":"US","duration":"oneMonth","number_type":"voip"}'
응답
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "charged": 4.99,
    "currency": "USD",
    "wallet_balance_after": 119.51
  }
}
POST /v1/numbers/{id}/renew Idempotency-Key 필수

번호 갱신

선택한 패키지만큼 번호를 연장합니다. 새 만료일은 현재 만료일에 더해지므로 미리 갱신해도 손해가 없습니다. 가격은 현재 사이트 요금으로 서버에서 계산됩니다. 만료된 번호는 갱신할 수 없으니 새 번호를 구매하세요.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • package enum body 선택 사항

    갱신 기간. 기본값 oneMonth. (duration도 레거시 별칭으로 허용됩니다.)

    다음 중 하나 oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header 필수

    갱신마다 새로 만들고, 재시도할 때는 그대로 다시 쓰는 UUID.

반환값

data에 갱신된 번호 객체, meta.charged, meta.currency, meta.wallet_balance_after 포함.

오류
  • 404계정에 있는 번호가 아닙니다.
  • 422insufficient_funds지갑 잔액이 갱신 비용보다 부족합니다.
  • 422만료, 취소되었거나 갱신할 수 없습니다.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/renew" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"package":"threeMonths"}'
응답
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-09-13T17:42:09Z"
  },
  "meta": {
    "charged": 12.99,
    "currency": "USD",
    "wallet_balance_after": 106.52
  }
}
POST /v1/numbers/{id}/cancel Idempotency-Key 필수

번호 취소 및 환불

번호를 해지하고 구매 금액 전액을 지갑으로 환불합니다. 구매 후 15분에서 120분 사이, 번호가 활성 상태이고 SMS를 받기 전에만 가능합니다. 조건에 맞지 않으면 422로 거부되며 아무것도 변경되지 않습니다. 너무 이른 경우 details.seconds_until_open에 기다려야 할 시간이 표시됩니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • Idempotency-Key string header 필수

    재시도할 때 그대로 다시 쓰는 UUID.

반환값

data에 번호 객체(status cancelled), meta.refunded, meta.currency, meta.wallet_balance_after 포함.

오류
  • 404계정에 있는 번호가 아닙니다.
  • 422너무 이르거나(15분 미만), 너무 늦었거나(120분 초과), 이미 SMS를 받았거나, 활성 상태가 아닙니다.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)"
응답
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "cancelled",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "refunded": 4.99,
    "currency": "USD",
    "wallet_balance_after": 124.50
  }
}

SMS

번호로 수신된 SMS를 읽습니다. 원본 텍스트가 전달되며, 코드 추출은 직접 하셔야 합니다.

SMS 메시지 객체

GET /numbers/{id}/sms가 반환하는 수신 SMS 하나. (GET /receive-sms는 camelCase 변형을 사용하며, 해당 엔드포인트에 표시되어 있습니다.)

필드
  • idinteger

    메시지 id.

  • fromstring

    발신자: 전화번호 또는 WhatsApp 같은 이름.

  • bodystring

    메시지 전체 텍스트.

  • received_atstring

    ISO 8601, UTC.

계속 전송되는 지원 중단 별칭: sender(= from), message(= body).

객체
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /v1/numbers/{id}/sms

번호와 SMS 조회

번호 하나와 그 번호가 받은 모든 SMS를 최신순으로 반환합니다. "이 번호 상세 보기" 화면이나 코드를 기다리며 한 번호를 폴링할 때 적합합니다. 본인 것이 아닌 id는 404를 반환합니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

반환값

data.number(번호 객체)와 data.messages(SMS 메시지 객체), meta.count.

오류
  • 404계정에 있는 번호가 아닙니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "number": {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    },
    "messages": [
      {
        "id": 9912,
        "from": "+18005550199",
        "body": "Your code is 432901",
        "received_at": "2026-05-13T17:43:14Z"
      }
    ]
  },
  "meta": { "count": 1 }
}
GET /v1/receive-sms

전화번호로 SMS 수신

소유한 번호의 SMS를 커서 기반 페이지로 조회하며, id 대신 전화번호로 지정합니다. 수신량이 많은 받은편지함에 적합합니다. 본인 번호가 아니면 403을 반환합니다.

매개변수
  • phoneNumber string query 필수

    E.164 형식 또는 숫자만, 예: +14035551234. +는 URL 인코딩하세요.

  • limit integer query 선택 사항

    페이지 크기 1-100. 기본값 50.

  • cursor string query 선택 사항

    이전 페이지의 meta.nextCursor.

응답 필드
  • data.messages[].idinteger

    메시지 id.

  • data.messages[].fromstring

    발신자.

  • data.messages[].tostring

    내 번호.

  • data.messages[].messagestring

    전체 텍스트.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    다음 페이지는 nextCursor를 cursor로 전달하세요.

오류
  • 403계정에 있는 번호가 아닙니다.
  • 422phoneNumber가 없거나 올바르지 않습니다.
curl --request GET "https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "phoneNumber": "+14035551234",
    "purchaseStatus": "active",
    "messages": [
      {
        "id": 1842,
        "from": "WhatsApp",
        "to": "+14035551234",
        "message": "Your verification code is 483920.",
        "receivedAt": "2026-05-13T17:43:14+00:00"
      }
    ]
  },
  "meta": {
    "count": 1,
    "pageSize": 50,
    "hasMore": false,
    "nextCursor": null,
    "prevCursor": null,
    "requestedAt": "2026-05-13T17:43:20+00:00"
  }
}

개인 이메일

비공개 번호마다 제공되는 무료 수신 전용 [email protected] 받은편지함. 번호당 주소 1개.

비공개 이메일 객체

번호 하나에 연결된 받은편지함.

필드
  • addressstring | null

    주소, 또는 받기 전에는 null.

  • statusenum

    active 또는 none.

  • unread_countinteger

    읽지 않은 이메일.

  • created_atstring | null

    주소를 받은 시각.

  • eligibleboolean

    번호가 지금 주소를 받을 수 있으면 true.

  • linked_numberstring

    주소가 속한 전화번호.

  • domainstring

    privnum.com

  • suggestionsstring[]

    받을 수 있는 경우 추천 이름.

객체
{
  "address": "[email protected]",
  "status": "active",
  "unread_count": 2,
  "created_at": "2026-07-03T10:15:00+00:00",
  "eligible": false,
  "linked_number": "+14035551234",
  "domain": "privnum.com",
  "suggestions": []
}
GET /v1/numbers/{id}/private-email

비공개 이메일 조회

번호의 주소, 또는 주소를 받기 전이라면 받을 수 있는지 여부와 추천 이름.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

반환값

data에 비공개 이메일 객체.

오류
  • 404계정에 있는 번호가 아닙니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "address": null,
    "status": "none",
    "unread_count": 0,
    "created_at": null,
    "eligible": true,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": ["alex.smith", "alex.smith42"]
  }
}
GET /v1/numbers/{id}/private-email/availability

이름 확인

받기 전에 이름이 유효하고 사용 가능한지 실시간으로 확인합니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • local_part string query 필수

    @ 앞부분: 영문자, 숫자, 점, 하이픈 또는 밑줄 3-64자.

응답 필드
  • availableboolean

    받을 수 있으면 true.

  • reasonenum | null

    too_short, too_long, invalid, reserved 또는 taken.

오류
  • 404계정에 있는 번호가 아닙니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /v1/numbers/{id}/private-email

주소 받기

활성 번호에 주소를 부여합니다. 무료이며 번호당 하나이고, 한 번 받은 주소는 다른 사람에게 절대 넘어가지 않습니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • local_part string body 필수

    확인한 이름.

반환값

data에 비공개 이메일 객체.

오류
  • 404본인 번호가 아니거나 아직 주소가 없습니다.
  • 422이름이 사용 중이거나 올바르지 않거나(details.reason), 번호에 이미 주소가 있거나, 번호가 활성 상태가 아닙니다.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"local_part":"alex.smith"}'
응답
{
  "success": true,
  "data": {
    "address": "[email protected]",
    "status": "active",
    "unread_count": 0,
    "created_at": "2026-07-03T10:15:00+00:00",
    "eligible": false,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": []
  }
}
GET /v1/numbers/{id}/private-email/inbox

이메일 목록

최신순 이메일 요약 목록. 페이지 기반 페이지네이션을 사용하며, 최상위에 읽지 않은 메일 수가 포함됩니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • page integer query 선택 사항

    페이지 번호. 기본값 1.

  • per_page integer query 선택 사항

    1-100. 기본값 25.

응답 필드
  • data[]array

    id, from_email, from_name, subject, preview, attachment_count, is_read, received_at.

  • metaobject

    current_page, per_page, total, last_page.

  • unread_countinteger

    최상위, data 옆.

오류
  • 404본인 번호가 아니거나 아직 주소가 없습니다.
  • 404private_email_closed번호가 취소 또는 환불되었습니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": [
    {
      "id": 77,
      "from_email": "[email protected]",
      "from_name": "Example Billing",
      "subject": "Your receipt",
      "preview": "Thanks for your order…",
      "attachment_count": 1,
      "is_read": false,
      "received_at": "2026-07-04T08:01:12+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
  "unread_count": 1
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/body

이메일 읽기

첨부 파일 목록을 포함한 전체 이메일(HTML 및 텍스트). 읽으면 읽음으로 표시됩니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • messageId integer path 필수

    받은편지함 목록의 이메일 id.

오류
  • 404본인 번호가 아니거나 아직 주소가 없습니다.
  • 404private_email_closed번호가 취소 또는 환불되었습니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": {
    "id": 77,
    "subject": "Your receipt",
    "from_email": "[email protected]",
    "from_name": "Example Billing",
    "received_at": "2026-07-04T08:01:12+00:00",
    "html": "<p>Thanks for your order…</p>",
    "text": "Thanks for your order…",
    "attachments": [
      { "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
    ]
  }
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}

첨부 파일 다운로드

자체 Content-Type과 파일 이름을 가진 원본 파일. index는 이메일의 attachments[]에서 가져옵니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • messageId integer path 필수

    받은편지함 목록의 이메일 id.

  • index integer path 필수

    이메일 읽기에서 받은 attachments[].index.

오류
  • 404본인 번호가 아니거나 아직 주소가 없습니다.
  • 404private_email_closed번호가 취소 또는 환불되었습니다.
  • 404해당 인덱스에 첨부 파일이 없습니다.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --output receipt.pdf
응답
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf

<binary file>
DELETE /v1/numbers/{id}/private-email/inbox/{messageId}

이메일 삭제

이메일과 첨부 파일을 삭제합니다.

매개변수
  • id integer path 필수

    GET /numbers의 번호 id.

  • messageId integer path 필수

    받은편지함 목록의 이메일 id.

오류
  • 404본인 번호가 아니거나 아직 주소가 없습니다.
  • 404private_email_closed번호가 취소 또는 환불되었습니다.
curl --request DELETE "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
응답
{
  "success": true,
  "data": null
}

AI & MCP

AI 어시스턴트가 계정을 직접 사용하게 하거나, 코딩 에이전트에 API 기반 개발에 필요한 모든 것을 제공하세요.

MCP 서버

REST API와 함께 Model Context Protocol 서버도 운영합니다. Claude, ChatGPT 또는 에디터에 연결하면 어시스턴트가 별도의 코드 없이 기본 도구로 가격과 재고를 확인하고, 번호를 구매하고, SMS를 읽을 수 있습니다. MCP가 처음이신가요? MCP 서버 개요부터 시작하세요.

엔드포인트
MCP 엔드포인트 · streamable HTTP
https://mcp.temp-number.com/mcp

로그인 방식

  • AI 앱에 URL을 추가하세요. 앱이 Temp Number로 안내하면 본인 계정으로 로그인합니다(PKCE를 사용하는 OAuth 2.1). 복사할 키가 없습니다.
  • 동의 화면에서 어시스턴트가 할 수 있는 작업을 선택합니다. 잔액, 가격, 보유 번호와 SMS 읽기는 항상 포함됩니다. 지갑으로 구매, 갱신, 취소하는 구매 허용은 체크하지 않으면 꺼져 있습니다.
  • 모든 연결은 대시보드 → MCP 서버 → 연결된 앱에 표시되며, 언제든지 연결을 해제할 수 있습니다.
  • 키 방식이 더 편하신가요(CI, 스크립트, 헤드리스 에이전트)? 같은 페이지에서 MCP 키를 만들어 Authorization: Bearer <key>로 보내세요. MCP 키와 REST API 키는 서로 호환되지 않습니다.

도구

도구기능"구매 허용" 필요
get-balance인증된 계정의 지갑 잔액과 청구 통화를 조회합니다.아니요
get-pricing전체 국가 또는 단일 ISO 국가 코드의 현재 가격 목록을 반환합니다.아니요
get-inventory국가, 기간 및 선택적 번호 유형별 실시간 재고 현황을 조회합니다.아니요
purchase-number지갑 잔액으로 인증된 계정용 개인 번호 1개를 구매합니다.예
list-active-numbers인증된 계정이 소유한 번호를 반환하며, 상태별로 필터링할 수 있습니다.아니요
check-sms인증된 계정이 소유한 구매 번호 ID의 SMS 메시지를 가져옵니다.아니요
renew-number선택적 기간 패키지를 사용해 ID로 구매한 번호를 갱신합니다.예
cancel-numberID로 구매한 번호를 취소하고 해당되는 지갑 환불을 반환합니다.예

AI 도구 연결하기

앱을 선택하세요. 대부분 클릭 한 번으로 연결됩니다. Temp Number에 로그인하고, 어시스턴트에 허용할 작업을 체크한 뒤 Allow를 클릭하세요.

Claude - claude.ai, 데스크톱 및 모바일

설치할 것이 없습니다. 브라우저, 데스크톱 앱, 모바일에서 모두 작동합니다.

  1. Claude에 추가를 클릭하세요. Temp Number와 URL이 미리 입력된 상태로 Claude가 열립니다. Add를 클릭하세요.
  2. Connect를 클릭하고 Temp Number에 로그인한 뒤, Claude의 구매 허용 여부를 선택하고 Allow를 클릭하세요.
  3. 아무 채팅에서나 + 메뉴 → Connectors를 열고 Temp Number를 켜세요. 예시: "미국 번호는 한 달에 얼마인가요?"
Team 및 Enterprise: 소유자가 조직 설정 → 커넥터에서 커넥터를 한 번 추가합니다. 그러면 각 멤버가 자신의 Temp Number 계정으로 로그인하므로 모두 자신의 지갑에서 결제합니다.

버튼이 없나요? Claude에서 Customize → Connectors → Add custom connector로 이동해 MCP 엔드포인트를 붙여넣으세요. Claude의 요청 헤더 옵션을 사용하는 조직은 로그인 대신 MCP 키를 Authorization: Bearer <key>로 보낼 수 있습니다.

llms.txt & 에이전트 프롬프트

AI 코딩 어시스턴트로 개발 중이신가요? 아래 컨텍스트를 제공하면 인증, 멱등성, 요청 한도까지 포함해 API를 한 번에 올바르게 연동할 수 있습니다.

llms.txt OpenAPI 스펙
prompt.md
You are integrating the Temp Number REST API. Read the full, machine-readable reference before writing any code:

- API reference (llms.txt): https://temp-number.com/developers/llms.txt
- OpenAPI spec: https://api.temp-number.com/api.json
- Base URL: https://api.temp-number.com/v1
- MCP server (for AI agents that call tools directly): https://mcp.temp-number.com/mcp - sign in with OAuth, or send an MCP key as a Bearer token.

Rules: authenticate every request with `Authorization: Bearer <YOUR_API_KEY>` (created in the dashboard → API Access) and keep the key in an environment variable, never in code; send and accept JSON over HTTPS; send a unique `Idempotency-Key` (UUID) header on every POST that buys, renews or cancels - it is required, and retries must reuse the same key; branch on the `code` field of error responses, not on the message text; on HTTP 429 or 503, wait for the `Retry-After` header. All prices are final USD.

Task: <describe what you want to build - e.g. "buy a US number, wait for the verification SMS, then cancel it if it never arrives">.
https://temp-number.com/developers/llms.txt은 모든 엔드포인트를 항상 최신 상태로 요약한 일반 텍스트 문서이며, OpenAPI 명세는 타입이 지정된 계약입니다. 둘 다 API와 함께 업데이트됩니다.

리소스

변경 사항과 도움을 받을 수 있는 곳입니다.

변경 내역

추가형 변경만 있었으며, /v1에서 제거된 항목은 없습니다.

  • NewMCP: Temp Number 계정으로 로그인

    원클릭 "Add to Claude"는 물론 ChatGPT, Claude Code, Codex, Cursor, VS Code도 키를 복사하지 않고 연결할 수 있습니다. AI의 결제 허용 여부는 동의 화면에서 선택합니다.

  • Docs문서가 새 위치로 이전했습니다

    빠른 시작, 검색, 그리고 cURL, Node.js, Python, PHP로 된 모든 예제. 오류, 요청 한도, 환불 내용이 이제 실제 API와 정확히 일치합니다.

  • New사이트 전체용 llms.txt

    AI 어시스턴트를 위한 서비스 개요 텍스트로, 에이전트용 API 레퍼런스로 연결됩니다.

  • NewAI 도구 연결하기

    Claude Code, Codex, Cursor, VS Code 설정 방법과 Cursor 및 VS Code용 원클릭 설치 링크.

  • NewOpenAPI 스펙

    기계가 읽을 수 있는 명세는 https://api.temp-number.com/api.json 에서 제공됩니다.

  • Improved객체가 레퍼런스와 일치합니다

    번호와 SMS는 ISO 8601 날짜와 from/body를 사용합니다. 오류에는 기계가 읽을 수 있는 code(out_of_stock, insufficient_funds, invalid_duration)가 포함됩니다. number_type을 생략하면 /inventory가 모든 번호 유형을 보여 줍니다. 이전 필드 이름도 지원 중단 별칭으로 계속 작동합니다.

  • New비공개 이메일 엔드포인트

    번호에 무료 [email protected] 받은편지함을 만들고, API로 메일을 읽고 첨부 파일을 내려받으세요.

  • NewMCP 서버

    AI 에이전트가 MCP 키로 가격 확인, 번호 구매, SMS 읽기를 도구로 사용할 수 있습니다.

  • Launch공개 REST API v1

    계정, 가격, 재고, 번호 수명 주기, SMS. Bearer 토큰 인증 사용.

지원

문제가 있거나 문서 내용이 API 동작과 다른가요? 문의하기 - 엔드포인트, 요청 시각, 응답 본문을 함께 보내 주세요(API 키는 절대 포함하지 마세요).

지금 바로 개발을 시작해 볼까요?

키를 만들고 1분 안에 첫 호출을 해 보세요.

로그인하고 시작하기