Платформа для розробників

Temp Number API — телефонні номери, SMS та OTP

Отримуйте віртуальні телефонні номери, приймайте SMS у реальному часі та автоматизуйте OTP-верифікацію — через зручний REST API або прямо зі свого ШІ-асистента.

REST · JSON MCP для ШІ-агентів cURL · Node.js · Python · PHP
БАЗОВИЙ URL https://api.temp-number.com/v1

Головна / Розробникам

Відкрити в ChatGPT Відкрити в Claude

Вступ

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)"

Автентифікація

Надсилайте свій API-ключ у стандартному заголовку Authorization з кожним запитом:

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 із двома знаками після коми, завжди ціна, яку ви сплачуєте.
  • Деякі об'єкти ще містять старіші назви полів для наявних інтеграцій (позначені в довіднику як застарілі). Новий код має їх ігнорувати.
Відповіді ніколи не називають вищого постачальника й не показують оптову вартість. Єдина ціна, яку ви бачите, — та, що списується з вашого гаманця, тож її безпечно показувати власним користувачам.

Помилки

Помилки використовують стандартні коди стану 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."} Надсилайте UUID в Idempotency-Key.
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-sms60 / хвна API-ключ
GET /receive-sms30 / хвна API-ключ і номер телефону
GET /receive-sms30 / хвна IP-адресу

Якщо ліміт перевищено, ви отримаєте 429 із заголовком Retry-After (у секундах). Зачекайте щонайменше стільки, а потім повторюйте з наростаючою затримкою та джитером. Відповіді також містять 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 назад як cursor з тим самим phoneNumber. Курсори непрозорі — не створюйте й не змінюйте їх.

наступна сторінка
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9

Списки, невеликі за своєю природою (/numbers, /pricing), повертають усе в одній відповіді; приватні вхідні використовують page і per_page.

Допустиме використання

API створено для розробників: сценарії верифікації та OTP, автоматизований онбординг, QA та системне тестування, а також будь-які продукти, яким потрібні вхідні SMS чи телефонні номери у великих обсягах.

  • Використовуйте його лише для законної верифікації, розробки та тестування.
  • Жодного шахрайства, спаму, обману чи введення в оману. Якщо номери використовуються для шахрайства чи іншої зловмисної діяльності, обліковий запис блокується негайно й без попередження, пов'язані номери скасовуються, а кошти не повертаються.
  • Не для регульованих облікових записів чи облікових записів, прив'язаних до особи. Наші спільні тимчасові номери не підтримують SMS-верифікацію для банківських, платіжних, криптовалютних, державних та інших сервісів, що перевіряють вашу юридичну особу (KYC/AML), — для них використовуйте власний особистий мобільний номер.
Ми відстежуємо зловживання. Повні умови — в наших Умовах надання послуг.

Довідник 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

    Доступні номери (сума за types[], якщо number_type не вказано).

  • 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}/…. Вебхуки надсилають його як 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 (мілісекунди epoch). Не покладайтеся на них.

об'єкт
{
  "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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • Idempotency-Key string header Обов'язково

    UUID, повторно використовується під час повторних спроб.

Повертає

Об'єкт номера (status cancelled) в data; 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-повідомлення

Одне отримане SMS у форматі GET /numbers/{id}/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 Обов'язково

    Id номера з GET /numbers.

Повертає

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] лише для отримання листів для кожного приватного номера. Одна адреса на номер.

Об'єкт приватної пошти

Скринька, прив'язана до одного номера.

Поля
  • 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 Обов'язково

    Id номера з GET /numbers.

Повертає

Об'єкт приватної пошти в 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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • 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 Обов'язково

    Id номера з GET /numbers.

  • 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
}

ШІ та MCP

Дозвольте ШІ-асистенту працювати з вашим акаунтом напряму або передайте агенту для програмування все необхідне, щоб будувати на основі API.

Сервер MCP

Поряд із REST API ми підтримуємо сервер Model Context Protocol. Підключіть його до Claude, ChatGPT або свого редактора — і асистент зможе перевіряти ціни й наявність, купувати номер і читати його SMS як вбудовані інструменти, без жодного коду з вашого боку. Вперше чуєте про MCP? Почніть з огляду сервера MCP.

Endpoint
Ендпоінт MCP · streamable HTTP
https://mcp.temp-number.com/mcp

Як працює вхід

  • Додайте URL-адресу у свій ШІ-застосунок. Він перенаправить вас на Temp Number, щоб увійти у власний акаунт (OAuth 2.1 з PKCE), — жодного ключа копіювати не потрібно.
  • На екрані згоди ви вибираєте, що може робити асистент. Перегляд балансу, цін, ваших номерів і їхніх SMS доступний завжди. Allow purchases — купівля, продовження та скасування з оплатою з гаманця — вимкнено, якщо ви не позначите цей пункт.
  • Усі підключення відображаються в розділі Панель керування → MCP-сервер → Підключені застосунки, де їх можна будь-коли від'єднати.
  • Вам зручніше ключ (CI, скрипти, агенти без інтерфейсу)? Створіть ключ MCP на тій самій сторінці й надсилайте його в заголовку Authorization: Bearer <key>. Ключі MCP і ключі REST API не взаємозамінні.

Інструменти

ІнструментЩо він робитьПотрібен дозвіл «Allow purchases»
get-balanceОтримати баланс гаманця автентифікованого акаунта та валюту розрахунків.Ні
get-pricingПовернути актуальний каталог цін для всіх країн або для одного коду країни ISO.Ні
get-inventoryПеревірити наявність номерів у реальному часі для країни, терміну та, за бажанням, типу номера.Ні
purchase-numberПридбати один приватний номер для автентифікованого акаунта за кошти гаманця.Так
list-active-numbersПовернути номери, що належать автентифікованому акаунту, за бажанням із фільтром за статусом.Ні
check-smsОтримати SMS-повідомлення для придбаного номера за ID, що належить автентифікованому акаунту.Ні
renew-numberПродовжити придбаний номер за ID, за бажанням вказавши пакет терміну.Так
cancel-numberСкасувати придбаний номер за ID і повернути на гаманець належну суму.Так

Підключіть свій ШІ-інструмент

Виберіть свій застосунок. Більшість підключається одним кліком: ви входите в Temp Number, позначаєте, що може робити асистент, і натискаєте Allow.

Claude — claude.ai, десктоп і мобільний застосунок

Нічого не потрібно встановлювати. Працює в браузері, десктопному застосунку та на мобільних пристроях.

  1. Натисніть Add to Claude. Claude відкриється з уже заповненими назвою Temp Number та URL-адресою. Натисніть Add.
  2. Натисніть Connect, увійдіть у Temp Number, виберіть, чи може Claude здійснювати покупки, і натисніть Allow.
  3. У будь-якому чаті відкрийте меню + → Connectors і ввімкніть Temp Number. Спробуйте: «Скільки коштує номер США на місяць?»
Team і Enterprise: власник один раз додає конектор у розділі Organization settings → Connectors. Потім кожен учасник входить у власний акаунт Temp Number, тож кожен витрачає кошти зі свого гаманця.

Немає кнопки? У Claude перейдіть до Customize → Connectors → Add custom connector і вставте ендпоінт MCP. Організації з опцією заголовків запиту в Claude можуть замість входу надсилати ключ MCP у заголовку Authorization: Bearer <key>.

llms.txt і промпт для агента

Працюєте з ШІ-асистентом для програмування? Дайте йому контекст нижче — і він правильно інтегрує 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.

  • Newllms.txt для всього сайту

    Текстова карта сервісу для AI-асистентів із посиланням на довідник API, готовий для агентів.

  • NewПідключіть свій ШІ-інструмент

    Налаштування для Claude Code, Codex, Cursor і VS Code з посиланнями для встановлення в один клік для Cursor і VS Code.

  • NewСпецифікація OpenAPI

    Машиночитна специфікація доступна за адресою https://api.temp-number.com/api.json.

  • ImprovedОб'єкти відповідають довіднику

    Номери та SMS використовують дати ISO 8601 і from/body. Помилки містять машиночитний код (out_of_stock, insufficient_funds, invalid_duration). /inventory повертає всі типи номерів, якщо не вказати number_type. Старі назви полів досі працюють як застарілі псевдоніми.

  • NewЕндпоінти приватної пошти

    Отримайте безкоштовну скриньку [email protected] для номера, читайте листи й завантажуйте вкладення через API.

  • NewСервер MCP

    AI-агенти можуть перевіряти ціни, купувати номери й читати SMS як інструменти за допомогою ключа MCP.

  • LaunchПублічний REST API v1

    Акаунт, ціни, наявність, життєвий цикл номера та SMS з автентифікацією Bearer-токеном.

Підтримка

Застрягли або знайшли в документації щось, що не відповідає роботі API? Напишіть нам — вкажіть ендпоінт, час запиту та тіло відповіді (ніколи не надсилайте свій API-ключ).

Готові почати?

Створіть ключ і зробіть перший виклик менш ніж за хвилину.

Увійдіть, щоб почати