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. Обліковий запис із непідтвердженою електронною поштою або заблокований повертає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; повідомлення призначене для людей. Див. Помилки. - Час у форматі 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 |
Акаунт ще не підтвердив свою електронну адресу. | Підтвердьте електронну адресу на сайті, а потім повторіть спробу. |
| 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.
Endpointhttps://mcp.temp-number.com/mcp
Як працює вхід
- Додайте URL-адресу у свій ШІ-застосунок. Він перенаправить вас на Temp Number, щоб увійти у власний акаунт (OAuth 2.1 з PKCE), — жодного ключа копіювати не потрібно.
- На екрані згоди ви вибираєте, що може робити асистент. Перегляд балансу, цін, ваших номерів і їхніх SMS доступний завжди. Allow purchases — купівля, продовження та скасування з оплатою з гаманця — вимкнено, якщо ви не позначите цей пункт.
- Усі підключення відображаються в розділі Панель керування → MCP-сервер → Підключені застосунки, де їх можна будь-коли від'єднати.
- Вам зручніше ключ (CI, скрипти, агенти без інтерфейсу)? Створіть ключ MCP на тій самій сторінці й надсилайте його в заголовку
Authorization: Bearer <key>. Ключі MCP і ключі REST API не взаємозамінні.
Інструменти
| Інструмент | Що він робить | Потрібен дозвіл «Allow purchases» |
|---|---|---|
get-balance | Отримати баланс гаманця автентифікованого акаунта та валюту розрахунків. | Ні |
get-pricing | Повернути актуальний каталог цін для всіх країн або для одного коду країни ISO. | Ні |
get-inventory | Перевірити наявність номерів у реальному часі для країни, терміну та, за бажанням, типу номера. | Ні |
purchase-number | Придбати один приватний номер для автентифікованого акаунта за кошти гаманця. | Так |
list-active-numbers | Повернути номери, що належать автентифікованому акаунту, за бажанням із фільтром за статусом. | Ні |
check-sms | Отримати SMS-повідомлення для придбаного номера за ID, що належить автентифікованому акаунту. | Ні |
renew-number | Продовжити придбаний номер за ID, за бажанням вказавши пакет терміну. | Так |
cancel-number | Скасувати придбаний номер за ID і повернути на гаманець належну суму. | Так |
Підключіть свій ШІ-інструмент
Виберіть свій застосунок. Більшість підключається одним кліком: ви входите в Temp Number, позначаєте, що може робити асистент, і натискаєте Allow.
Claude — claude.ai, десктоп і мобільний застосунок
Нічого не потрібно встановлювати. Працює в браузері, десктопному застосунку та на мобільних пристроях.
- Натисніть 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
«Add to Claude» в один клік, а також ChatGPT, Claude Code, Codex, Cursor і VS Code без копіювання ключа. На екрані згоди ви вирішуєте, чи може AI витрачати кошти.
-
DocsНове місце для документації
Швидкий старт, пошук і всі приклади на cURL, Node.js, Python і PHP. Помилки, ліміти запитів і повернення коштів тепер точно відповідають робочому API.
-
Newllms.txt для всього сайту
Текстова карта сервісу для AI-асистентів із посиланням на довідник API, готовий для агентів.
-
NewПідключіть свій ШІ-інструмент
Налаштування для Claude Code, Codex, Cursor і VS Code з посиланнями для встановлення в один клік для Cursor і VS Code.
-
NewСпецифікація OpenAPI
Машиночитна специфікація доступна за адресою https://api.temp-number.com/api.json.
-
ImprovedОб'єкти відповідають довіднику
Номери та SMS використовують дати ISO 8601 і from/body. Помилки містять машиночитний код (out_of_stock, insufficient_funds, invalid_duration). /inventory повертає всі типи номерів, якщо не вказати number_type. Старі назви полів досі працюють як застарілі псевдоніми.
-
NewЕндпоінти приватної пошти
Отримайте безкоштовну скриньку [email protected] для номера, читайте листи й завантажуйте вкладення через API.
-
NewСервер MCP
AI-агенти можуть перевіряти ціни, купувати номери й читати SMS як інструменти за допомогою ключа MCP.
-
LaunchПублічний REST API v1
Акаунт, ціни, наявність, життєвий цикл номера та SMS з автентифікацією Bearer-токеном.
Підтримка
Застрягли або знайшли в документації щось, що не відповідає роботі API? Напишіть нам — вкажіть ендпоінт, час запиту та тіло відповіді (ніколи не надсилайте свій API-ключ).
Готові почати?
Створіть ключ і зробіть перший виклик менш ніж за хвилину.