Temp Number API — телефонные номера, SMS и OTP
Подключайте виртуальные телефонные номера, принимайте SMS в реальном времени и автоматизируйте OTP-верификацию — через понятный REST API или прямо из вашего ИИ-ассистента.
https://api.temp-number.com/v1
Главная / Разработчикам
Введение
Temp Number API построен вокруг предсказуемых ресурсов, использует стандартные HTTP-методы и возвращает JSON в каждом ответе. Один ключ даёт доступ на чтение и запись только к вашему аккаунту — доступа к чужим аккаунтам нет.
Быстрый старт
С нуля до кода подтверждения. Выберите язык один раз — все примеры на странице переключатся на него.
-
Создайте API-ключ
Создайте ключ в разделе Панель → Доступ к API. Он показывается один раз: сохраните его в переменной окружения
TEMP_NUMBER_API_KEY. -
Проверьте баланс
Каждый вызов передаёт ваш ключ в заголовке Authorization. Начните с чего-нибудь безобидного: баланса кошелька.
curl --request GET "https://api.temp-number.com/v1/account" \ --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \ --header "Accept: application/json"const response = await fetch("https://api.temp-number.com/v1/account", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/account", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/account'); $result = $response->json(); -
Выберите страну и проверьте наличие
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"const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/inventory", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, params={"country_code": "US", "duration": "oneMonth"}, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/inventory', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
Купить номер
Передавайте новый 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"}'import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/buy", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ country_code: "US", duration: "oneMonth" }), }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/buy", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, json={"country_code": "US", "duration": "oneMonth"}, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/buy', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
Прочитайте SMS
Опрашивайте номер каждые несколько секунд, пока не придёт сообщение. Вы получаете исходный текст; код извлекайте на своей стороне.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \ --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \ --header "Accept: application/json"const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/numbers/1482/sms", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/numbers/1482/sms'); $result = $response->json(); -
Нет 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)"import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Idempotency-Key": randomUUID(), }, }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/1482/cancel", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/1482/cancel'); $result = $response->json();
Аутентификация
Передавайте API-ключ в стандартном заголовке Authorization в каждом запросе:
Authorization: Bearer YOUR_API_KEY
- Создавайте ключи в разделе Доступ к API. Ключ показывается полностью только один раз — при создании.
- Используйте отдельный ключ для каждой интеграции, чтобы отозвать один, не затрагивая остальные. При смене пароля отзываются все ключи.
- При отсутствующем, неверном или отозванном ключе возвращается
401. Если email аккаунта не подтверждён или аккаунт заблокирован, возвращается403сcodeemail_unverifiedилиaccount_suspended. - REST-ключи работают только с
/v1. MCP-сервер использует собственный вход или MCP-ключи — см. MCP-сервер.
Базовый URL и версии
Все эндпоинты находятся под постоянным префиксом /v1:
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 с дополнительным контекстом.
{
"success": false,
"message": "Insufficient wallet balance.",
"code": "insufficient_funds"
}
{
"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-sms | 60 / минуту | на один API-ключ |
| GET /receive-sms | 30 / минуту | на API-ключ и номер телефона |
| GET /receive-sms | 30 / минуту | на один IP-адрес |
При превышении лимита вы получите 429 с заголовком Retry-After (в секундах). Подождите не меньше указанного времени, затем повторяйте с увеличивающейся задержкой и случайным разбросом. Ответы также содержат X-RateLimit-Limit и X-RateLimit-Remaining.
Идемпотентность
Для 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. Запросы справа — на выбранном вами языке; ответы показаны в реальном формате.
Аккаунт
Узнайте баланс кошелька и валюту расчётов.
/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"
const response = await fetch("https://api.temp-number.com/v1/account", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/account",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/account');
$result = $response->json();
{
"success": true,
"balance": 124.50,
"currency": "USD"
}
Цены и наличие
Просматривайте актуальные рынки, точную цену за каждый срок и наличие в реальном времени.
Объект цен по стране
Одна страна и все пакеты, которые там можно купить. price — итоговая сумма списания с кошелька; закупочная стоимость никогда не раскрывается.
Поля-
country_codestringКод ISO 3166-1 alpha-2, например US.
-
country_namestringОтображаемое имя.
-
packages[].number_typeenumvoip или 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
}
]
}
/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"
const response = await fetch("https://api.temp-number.com/v1/pricing", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing');
$result = $response->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 }
}
/v1/pricing/{countryCode}
Получить цены для одной страны
Актуальные цены для одной страны. 404 означает, что для страны сейчас нет активного маршрута: считайте это временным отсутствием в наличии, а не «никогда не продаётся».
Параметры-
countryCodestring 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"
const response = await fetch("https://api.temp-number.com/v1/pricing/GB", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing/GB",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing/GB');
$result = $response->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
}
]
}
}
/v1/inventory
Проверить наличие
Наличие в реальном времени для страны и срока, чтобы отключить кнопку «Купить» до того, как на неё нажмут. Не указывайте number_type, чтобы получить все типы рядом в types[]. Зелёный результат — надёжный сигнал, но окончательной проверкой остаётся сама покупка.
Параметры-
country_codestring query ОбязательныйКод страны ISO 3166-1 alpha-2.
-
durationenum query НеобязательноКлюч срока из GET /pricing/{countryCode}. Не указывайте, чтобы использовать срок по умолчанию для маршрута.
Одно изhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query НеобязательноОграничьте проверку одним типом. Не указывайте, чтобы увидеть все типы.
Одно изvoipnon_voip
-
stockinteger | nullДоступные номера (сумма по types[], если number_type не указан).
-
availablebooleanTrue, если можно купить хотя бы один номер.
-
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"
const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/inventory",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"country_code": "US", "duration": "oneMonth"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/inventory', [
'country_code' => 'US',
'duration' => 'oneMonth',
]);
$result = $response->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_numberstringE.164, например +14035551234.
-
country_codestring | nullISO 3166-1 alpha-2.
-
country_namestringОтображаемое имя.
-
number_typeenumvoip или non_voip.
-
statusenumactive, expired, cancelled или refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 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"
}
/v1/numbers
Список ваших номеров
Все номера вашего аккаунта, сначала новые. Используйте status=expiring_soon (активные номера, у которых до окончания срока осталось не более 10 дней), чтобы отправлять напоминания о продлении.
Параметры-
statusenum 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"
const response = await fetch("https://api.temp-number.com/v1/numbers?status=expiring_soon", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"status": "expiring_soon"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers', [
'status' => 'expiring_soon',
]);
$result = $response->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" }
}
/v1/numbers/buy
Требуется Idempotency-Key Купить номер
Выделяет новый приватный номер и списывает средства с кошелька за один атомарный шаг. Если после списания выдать номер не удалось, списание отменяется: вы никогда не останетесь без номера после оплаты. В ответе указаны списанная сумма и баланс после операции.
Параметры-
country_codestring body ОбязательныйСтрана из GET /pricing.
-
durationenum body ОбязательныйКлюч срока из packages[] этой страны — у каждой страны свой набор.
Одно изhalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body НеобязательноНе указывайте, чтобы использовать значение маршрута по умолчанию.
Одно изvoipnon_voip -
Idempotency-Keystring header ОбязательныйUUID, новый для каждой покупки, повторяется при повторных попытках.
Новый объект номера в data; meta.charged, meta.currency, meta.wallet_balance_after.
Ошибки- 422
insufficient_fundsНа кошельке недостаточно средств для оплаты. - 422
out_of_stockРаспродано после вашей проверки наличия. - 422
invalid_durationЭтот срок не продаётся для данной страны/типа. - 403
kyc_requiredСначала нужна проверка личности. Средства не списаны. - 503
purchases_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/buy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ country_code: "US", duration: "oneMonth", number_type: "voip" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/buy",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"country_code": "US", "duration": "oneMonth", "number_type": "voip"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/buy', [
'country_code' => 'US',
'duration' => 'oneMonth',
'number_type' => 'voip',
]);
$result = $response->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": {
"charged": 4.99,
"currency": "USD",
"wallet_balance_after": 119.51
}
}
/v1/numbers/{id}/renew
Требуется Idempotency-Key Продлить номер
Продлевает номер на выбранный пакет. Новый срок добавляется к текущему, поэтому при раннем продлении вы ничего не теряете. Цена — текущий тариф сайта, рассчитывается на нашей стороне. Истёкшие номера продлить нельзя: купите новый.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
packageenum body НеобязательноСрок продления. По умолчанию oneMonth. (duration принимается как устаревший псевдоним.)
Одно изoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ОбязательныйUUID, новый для каждого продления, повторяется при повторных попытках.
Обновлённый объект номера в data; meta.charged, meta.currency, meta.wallet_balance_after.
Ошибки- 404Этого номера нет в вашем аккаунте.
- 422
insufficient_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/renew", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ package: "threeMonths" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/renew",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"package": "threeMonths"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/renew', [
'package' => 'threeMonths',
]);
$result = $response->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-09-13T17:42:09Z"
},
"meta": {
"charged": 12.99,
"currency": "USD",
"wallet_balance_after": 106.52
}
}
/v1/numbers/{id}/cancel
Требуется Idempotency-Key Отмена номера с возвратом средств
Освобождает номер и возвращает его полную стоимость на кошелёк. Разрешено только в период от 15 до 120 минут после покупки, пока номер активен и на него не пришло ни одного SMS. Вне этих условий вызов отклоняется с кодом 422 и ничего не меняется; если слишком рано, details.seconds_until_open показывает, сколько ждать.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
Idempotency-Keystring 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)"
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Idempotency-Key": randomUUID(),
},
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/cancel",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/cancel');
$result = $response->json();
{
"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, показанный у этого эндпоинта.)
Поля-
idintegerId сообщения.
-
fromstringОтправитель: номер телефона или имя, например WhatsApp.
-
bodystringПолный текст сообщения.
-
received_atstringISO 8601, UTC.
Устаревшие псевдонимы, которые ещё отправляются: sender (= from) и message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Получите номер и его SMS
Один номер вместе со всеми полученными SMS, сначала новые. Лучше всего подходит для экрана «подробнее о номере» и для опроса одного номера в ожидании кода. Для чужих id возвращается 404.
Параметры-
idinteger 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/sms');
$result = $response->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 }
}
/v1/receive-sms
Получение SMS по номеру телефона
SMS с курсорной пагинацией для вашего номера, адресуемого по номеру телефона, а не по id. Лучше всего подходит для ящиков с большим объёмом сообщений. Для чужого номера возвращается 403.
Параметры-
phoneNumberstring query ОбязательныйE.164 или только цифры, например +14035551234. Кодируйте + в URL.
-
limitinteger query НеобязательноРазмер страницы 1–100. По умолчанию 50.
-
cursorstring query Необязательноmeta.nextCursor из предыдущей страницы.
-
data.messages[].idintegerId сообщения.
-
data.messages[].fromstringОтправитель.
-
data.messages[].tostringВаш номер.
-
data.messages[].messagestringПолный текст.
-
data.messages[].receivedAtstringISO 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"
const response = await fetch("https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/receive-sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"phoneNumber": "+14035551234", "limit": 50},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/receive-sms', [
'phoneNumber' => '+14035551234',
'limit' => 50,
]);
$result = $response->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, пока он не получен.
-
statusenumactive или none.
-
unread_countintegerНепрочитанные письма.
-
created_atstring | nullКогда адрес был получен.
-
eligiblebooleanTrue, если номер может получить адрес прямо сейчас.
-
linked_numberstringНомер телефона, к которому он относится.
-
domainstringprivnum.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": []
}
/v1/numbers/{id}/private-email
Получить приватную почту
Адрес номера или, пока адрес не получен, может ли номер его получить, и несколько вариантов имени.
Параметры-
idinteger 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email');
$result = $response->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"]
}
}
/v1/numbers/{id}/private-email/availability
Проверить имя
Проверка в реальном времени, что имя допустимо и свободно, прежде чем его занять.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
local_partstring query ОбязательныйЧасть до @: 3–64 буквы, цифры, точки, дефисы или подчёркивания.
-
availablebooleanTrue, если его можно занять.
-
reasonenum | nulltoo_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/availability",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"local_part": "alex.smith"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/availability', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"success": true,
"data": {
"local_part": "alex.smith",
"address": "[email protected]",
"available": true,
"reason": null,
"message": "Available"
}
}
/v1/numbers/{id}/private-email
Получить адрес
Назначает активному номеру адрес. Бесплатно, один на номер; полученный адрес никогда не передаётся другим.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
local_partstring 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"}'
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({ local_part: "alex.smith" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
json={"local_part": "alex.smith"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/private-email', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"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": []
}
}
/v1/numbers/{id}/private-email/inbox
Список писем
Краткие сведения о письмах, сначала новые, с постраничной пагинацией и количеством непрочитанных на верхнем уровне.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
pageinteger query НеобязательноНомер страницы. По умолчанию 1.
-
per_pageinteger query Необязательно1–100. По умолчанию 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerВерхний уровень, рядом с data.
- 404Не ваш номер, или адреса ещё нет.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"page": 1, "per_page": 25},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox', [
'page' => 1,
'per_page' => 25,
]);
$result = $response->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
}
/v1/numbers/{id}/private-email/inbox/{messageId}/body
Прочитать письмо
Полное письмо (HTML и текст) со списком вложений. При чтении письмо отмечается прочитанным.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
messageIdinteger path ОбязательныйId письма из списка входящих.
- 404Не ваш номер, или адреса ещё нет.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body');
$result = $response->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 }
]
}
}
/v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}
Скачать вложение
Исходный файл со своими Content-Type и именем. index берётся из attachments[] письма.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
messageIdinteger path ОбязательныйId письма из списка входящих.
-
indexinteger path Обязательныйattachments[].index из запроса «Прочитать письмо».
- 404Не ваш номер, или адреса ещё нет.
- 404
private_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
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
},
});
await writeFile("receipt.pdf", Buffer.from(await response.arrayBuffer()));
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
},
timeout=30,
)
with open("receipt.pdf", "wb") as file:
file.write(response.content)
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->sink(storage_path('receipt.pdf'))
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0');
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf
<binary file>
/v1/numbers/{id}/private-email/inbox/{messageId}
Удалить письмо
Удаляет письмо и его вложения.
Параметры-
idinteger path ОбязательныйId номера из GET /numbers.
-
messageIdinteger path ОбязательныйId письма из списка входящих.
- 404Не ваш номер, или адреса ещё нет.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.delete(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->delete('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77');
$result = $response->json();
{
"success": true,
"data": null
}
ИИ и MCP
Позвольте ИИ-ассистенту работать с вашим аккаунтом напрямую или дайте агенту для программирования всё необходимое для работы с API.
MCP-сервер
Помимо REST API, у нас работает сервер Model Context Protocol. Подключите его к Claude, ChatGPT или своему редактору — и ассистент сможет проверять цены и наличие, покупать номер и читать его SMS как встроенные инструменты, без кода с вашей стороны. Впервые слышите о MCP? Начните с обзора MCP-сервера.
Адрес запроса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, десктоп и мобильное приложение
Ничего не нужно устанавливать. Работает в браузере, десктопном и мобильном приложении.
- Нажмите Add to Claude. Claude откроется с уже заполненными названием Temp Number и URL. Нажмите Add.
- Нажмите Connect, войдите в Temp Number, решите, может ли Claude совершать покупки, и нажмите Allow.
- В любом чате откройте меню + → Connectors и включите Temp Number. Попробуйте: «Сколько стоит номер США на месяц?»
Нет кнопки? В Claude откройте Customize → Connectors → Add custom connector и вставьте эндпоинт MCP. Организации, у которых в Claude есть опция заголовков запроса, могут вместо входа отправлять MCP-ключ в заголовке Authorization: Bearer <key>.
ChatGPT
Нужен ChatGPT Business, Enterprise или Edu в веб-версии. В Business его добавляет администратор или владелец.
- Скопируйте URL сервера ниже, затем нажмите Открыть ChatGPT, чтобы перейти на страницу Plugins. В ChatGPT нет ссылки, которая заполнит это за вас.
- Нажмите + → Add custom MCP server. Назовите его Temp Number и вставьте URL в поле Connection.
- Выберите аутентификацию OAuth, примите предупреждение о рисках и нажмите Create as a plugin.
- Когда ChatGPT попросит, войдите в Temp Number, решите, может ли ChatGPT совершать покупки, и нажмите Allow.
- В новом чате введите @ и выберите Temp Number. Попробуйте: «Сколько стоит номер США на месяц?»
https://mcp.temp-number.com/mcp
Claude Code
Добавьте сервер один раз, затем войдите прямо в Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Запустите Claude Code и введите
/mcp. - Выберите temp-number → Authenticate. Откроется браузер: войдите и нажмите Allow.
Использование MCP-ключа (CI / без интерфейса)
export TEMPNUMBER_MCP_KEY=your-mcp-key
claude mcp add --transport http temp-number \
https://mcp.temp-number.com/mcp \
--header "Authorization: Bearer $TEMPNUMBER_MCP_KEY"
Codex CLI
Добавьте сервер и войдите. Codex сохранит сессию за вас.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Использование MCP-ключа (CI / без интерфейса)
В ~/.codex/config.toml. Ключ берётся из переменных окружения, поэтому файлом можно спокойно делиться.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Один клик, затем вход, когда Cursor попросит.
Или добавьте его в .cursor/mcp.json (или ~/.cursor/mcp.json). Затем Cursor покажет Needs login рядом с сервером: нажмите, войдите и нажмите Allow.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Использование MCP-ключа
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Один клик, затем вход при первом запуске инструмента.
Или добавьте его в .vscode/mcp.json — обратите внимание, что ключ называется servers, а не mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Использование MCP-ключа
VS Code запросит ключ один раз и сохранит его в защищённом хранилище.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${input:tempnumber-mcp-key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "tempnumber-mcp-key",
"description": "Temp Number MCP key",
"password": true
}
]
}
Любое другое MCP-приложение
Windsurf, Zed, LibreChat, ваш собственный агент…
- Добавьте эндпоинт MCP как удалённый сервер (streamable HTTP). Приложения с поддержкой входа сами находят его по адресу
https://mcp.temp-number.com/.well-known/oauth-protected-resourceи открывают экран согласия Temp Number. - Приложения без поддержки входа могут отправлять MCP-ключ в заголовке
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
llms.txt и промпт для агента
Работаете с ИИ-ассистентом для программирования? Передайте ему контекст ниже — и он правильно интегрирует API с первого раза, включая авторизацию, идемпотентность и лимиты запросов.
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-ключ).
Готовы начать?
Создайте ключ и выполните первый запрос меньше чем за минуту.