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

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. Если email аккаунта не подтверждён или аккаунт заблокирован, возвращается 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; message предназначен для людей. См. раздел Ошибки.
  • Время указывается в формате 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 Аккаунт ещё не подтвердил свой email. Подтвердите email на сайте и повторите попытку.
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-сервера.

Адрес запроса
Эндпоинт MCP · streamable HTTP
https://mcp.temp-number.com/mcp

Как работает вход

  • Добавьте URL в своё ИИ-приложение. Оно перенаправит вас в Temp Number, чтобы войти в свой аккаунт (OAuth 2.1 с PKCE) — копировать ключ не нужно.
  • На экране согласия вы выбираете, что разрешено ассистенту. Чтение баланса, цен, ваших номеров и их SMS доступно всегда. Разрешить покупки — покупка, продление и отмена с оплатой из кошелька — выключено, пока вы не отметите этот пункт.
  • Все подключения перечислены в разделе Панель → MCP-сервер → Подключённые приложения, где их можно отключить в любой момент.
  • Предпочитаете ключ (CI, скрипты, агенты без интерфейса)? Создайте MCP-ключ на той же странице и отправляйте его в заголовке Authorization: Bearer <key>. MCP-ключи и ключи REST API не взаимозаменяемы.

Инструменты

ИнструментЧто делаетТребуется «Разрешить покупки»
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: владелец один раз добавляет коннектор в разделе «Настройки организации» → «Коннекторы». Затем каждый участник входит со своим аккаунтом 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

    «Добавить в Claude» в один клик, а также ChatGPT, Claude Code, Codex, Cursor и VS Code без копирования ключа. На экране согласия вы решаете, может ли ИИ тратить средства.

  • DocsНовый дом для документации

    Быстрый старт, поиск и все примеры на cURL, Node.js, Python и PHP. Ошибки, лимиты запросов и возвраты теперь точно соответствуют работающему API.

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

    Текстовая карта сервиса для ИИ-ассистентов со ссылкой на справочник 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.

  • NewMCP-сервер

    ИИ-агенты могут проверять цены, покупать номера и читать SMS как инструменты с помощью ключа MCP.

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

    Аккаунт, цены, наличие, жизненный цикл номера и SMS с авторизацией по Bearer-токену.

Поддержка

Возникли трудности или нашли в документации расхождение с работой API? Свяжитесь с нами — укажите эндпоинт, время запроса и тело ответа (но никогда не API-ключ).

Готовы начать?

Создайте ключ и выполните первый запрос меньше чем за минуту.

Войдите, чтобы начать