API Temp Number - Números de telefone, SMS e OTP
Disponibilize números de telefone virtuais, receba SMS em tempo real e automatize a verificação OTP - a partir de uma API REST simples ou diretamente do seu assistente de IA.
https://api.temp-number.com/v1
Início / Programadores
Introdução
A API Temp Number está organizada em torno de recursos previsíveis, usa verbos HTTP padrão e devolve JSON em todas as respostas. Uma chave dá acesso de leitura e escrita apenas à sua conta - não existe acesso entre contas.
Início rápido
Do zero a um código de verificação. Escolha a sua linguagem uma vez - todos os exemplos da página seguem-na.
-
Criar uma chave de API
Em Painel → Acesso à API, crie uma chave. É mostrada uma única vez: guarde-a como a variável de ambiente
TEMP_NUMBER_API_KEY. -
Consultar o saldo
Todas as chamadas levam a sua chave no cabeçalho Authorization. Comece por algo inofensivo: o saldo da sua carteira.
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(); -
Escolha um país e verifique o stock
GET /pricing lista todos os países com o preço exato por duração. Depois, confirme o stock do que pretende.
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(); -
Comprar um número
Envie uma Idempotency-Key nova em cada compra. Se a ligação falhar, tente novamente com a mesma chave: nunca será cobrado duas vezes. Guarde o data.id da resposta.
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(); -
Ler o SMS
Consulte o número a cada poucos segundos até a mensagem chegar. Recebe o texto em bruto; extraia o código do seu lado.
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(); -
Sem SMS? Cancele e receba o reembolso
Entre 15 e 120 minutos após a compra, um número que não tenha recebido SMS pode ser cancelado com reembolso total para a sua carteira.
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();
Autenticação
Envie a sua chave de API no cabeçalho padrão Authorization em cada pedido:
Authorization: Bearer YOUR_API_KEY
- Crie chaves em Acesso à API. Cada chave é mostrada por completo uma única vez, no momento da criação.
- Use uma chave por integração, para poder revogar uma sem afetar as outras. Alterar a palavra-passe revoga todas as chaves.
- Uma chave em falta, mal formada ou revogada responde com
401. Uma conta que não verificou o email, ou que está suspensa, responde com403e ocodeemail_unverifiedouaccount_suspended. - As chaves REST funcionam apenas em
/v1. O servidor MCP usa o seu próprio início de sessão ou chaves MCP - consulte Servidor MCP.
URL base e versões
Todos os endpoints estão sob o prefixo permanente /v1:
https://api.temp-number.com/v1
As alterações aditivas - novos campos, endpoints ou parâmetros opcionais - são lançadas sem mudança de versão, por isso ignore os campos que não conhece. Uma alteração incompatível seria lançada em /v2; a sua integração nunca é migrada sem aviso. O contrato legível por máquina é a especificação OpenAPI.
Pedidos e respostas
- Envie corpos JSON com
Content-Type: application/jsoneAccept: application/jsonem cada pedido. - Sucesso:
{ "success": true, "data": …, "meta": {…} }.metainclui contagens, paginação e resumos monetários. - Erros:
{ "success": false, "message": "…", "code": "…" }. Usecodena lógica; a mensagem destina-se a pessoas. Consulte Erros. - As horas estão em ISO 8601. Os valores estão em USD com duas casas decimais - sempre o preço que paga.
- Alguns objetos ainda mantêm nomes de campos antigos para integrações existentes (marcados como obsoletos na referência). O código novo deve ignorá-los.
Erros
Os erros usam códigos de estado HTTP padrão. Os erros de negócio incluem um code estável e legível por máquina; alguns incluem details com mais contexto.
{
"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."]
}
}
| Estado | code | Significado | O que fazer |
|---|---|---|---|
| 400 | - | O cabeçalho Idempotency-Key está em falta ou mal formado na compra, renovação ou cancelamento. Corpo: {"error": "Missing Idempotency-Key header."} | Envie um UUID em Idempotency-Key. |
| 401 | - | Sem token bearer, token mal formado ou chave revogada. | Verifique o cabeçalho Authorization; crie uma nova chave se tiver sido revogada. |
| 403 | email_unverified |
A conta ainda não confirmou o endereço de e-mail. | Confirme o e-mail no site e tente novamente. |
| 403 | account_suspended |
A conta está suspensa. | Contacte o apoio ao cliente. |
| 403 | kyc_required |
A conta tem de verificar a identidade antes de comprar novos números. Nada foi cobrado; as renovações continuam a funcionar. | Conclua a verificação de identidade nas definições da conta e tente novamente. |
| 403 | - | A chave não tem acesso à API (uma chave MCP, por exemplo), ou GET /receive-sms foi pedido para um número de outra conta. | Utilize uma chave da API REST; consulte apenas os seus próprios números. |
| 404 | - | O número, a mensagem ou o país não pertence à sua conta ou não está à venda neste momento. Os ids de outras contas também respondem 404. | Volte a listar com GET /numbers ou GET /pricing. |
| 404 | private_email_closed |
A caixa de entrada privada está encerrada porque o respetivo número foi cancelado ou reembolsado. | Nada para repetir. |
| 409 | - | A Idempotency-Key já foi utilizada com um corpo diferente, ou o primeiro pedido com ela ainda está em curso. | Utilize uma nova chave para um novo pedido; aguarde e tente novamente para o que está em curso. |
| 422 | insufficient_funds |
A carteira não tem saldo suficiente para o preço. | Carregue a carteira e tente novamente. |
| 422 | out_of_stock |
O mercado esgotou entre a sua consulta de preço e a compra. | Volte a consultar GET /inventory e escolha outra duração ou tipo. |
| 422 | invalid_duration |
A duração não está disponível para esse país e tipo de número. | Volte a obter GET /pricing/{countryCode}. |
| 422 | - | A validação falhou (um objeto `errors` indica cada campo) ou uma regra recusou a ação, como cancelar fora do prazo de reembolso. | Leia `message`; corrija o pedido em vez de o repetir. |
| 429 | - | Limite de pedidos atingido. | Aguarde o tempo indicado no cabeçalho Retry-After e tente novamente com backoff. |
| 503 | purchases_paused |
As novas compras estão suspensas em toda a plataforma. Nada foi cobrado; as renovações e os cancelamentos continuam a funcionar. | Tente novamente após Retry-After (60 s). |
| 5xx | - | Algo falhou do nosso lado. | Tente novamente com a MESMA Idempotency-Key - nunca será cobrado duas vezes. |
Limites de pedidos
Os limites aplicam-se por chave e, além disso, as chamadas que movimentam dinheiro têm um limite mais restrito por conta:
| Aplica-se a | Limite | Contabilizado |
|---|---|---|
| Todos os endpoints | 60 / minuto | por chave de API |
| Comprar, renovar, cancelar | 10 / minuto | por conta, além dos limites acima |
| GET /receive-sms | 60 / minuto | por chave de API |
| GET /receive-sms | 30 / minuto | por chave de API e número de telefone |
| GET /receive-sms | 30 / minuto | por endereço IP |
Acima de um limite recebe 429 com um cabeçalho Retry-After (segundos). Aguarde pelo menos esse tempo e depois recue com jitter. As respostas também incluem X-RateLimit-Limit e X-RateLimit-Remaining.
Idempotência
POST /numbers/buy, /renew e /cancel exigem um cabeçalho Idempotency-Key: um UUID que cria para cada nova ação. Se a rede falhar, envie o mesmo pedido com a mesma chave - recebe a resposta original (marcada com X-Idempotency-Replayed: true) e nunca é cobrado duas vezes.
- Chave em falta:
400. As chaves têm até 128 caracteres de letras, dígitos e- _ . : - Mesma chave com um corpo diferente:
409. Mesma chave enquanto o primeiro pedido ainda está em curso:409- aguarde um momento e tente novamente. - As chaves são memorizadas por conta e por endpoint. Nunca reutilize uma chave para uma compra diferente.
Paginação
GET /receive-sms usa paginação por cursor, dos mais recentes para os mais antigos. Leia meta.hasMore; enquanto for true, envie meta.nextCursor de volta como cursor com o mesmo phoneNumber. Os cursores são opacos - não os construa nem os edite.
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9
As listas que são pequenas por natureza (/numbers, /pricing) devolvem tudo numa única resposta; a caixa de entrada privada usa page e per_page.
Utilização aceitável
A API foi criada para programadores: fluxos de verificação e OTP, onboarding automatizado, QA e testes de sistemas, e qualquer produto que precise de SMS recebidos ou de números de telefone em grande escala.
- Utilize-a apenas para verificação legítima, desenvolvimento e testes.
- Sem burlas, spam, fraude ou engano. Os números usados para burlas ou outras atividades abusivas levam ao banimento imediato e sem aviso da conta, ao cancelamento dos números associados e não dão direito a reembolso.
- Não se destina a contas reguladas ou associadas à identidade. Os nossos números temporários e partilhados não suportam a verificação por SMS para serviços bancários, de pagamento, de criptomoedas, governamentais ou outros que verifiquem a sua identidade legal (KYC/AML) - para esses, use o seu próprio número de telemóvel pessoal.
Referência da API
Todos os endpoints /v1 ativos. Os pedidos estão à direita na sua linguagem; as respostas têm a estrutura real.
Conta
Consulte o saldo da sua carteira e a moeda de liquidação.
/v1/account
Obter o saldo da conta
Devolve o saldo disponível na carteira e a respetiva moeda. Consulte-o antes de uma compra para poder parar a tempo com uma mensagem clara de "carregue a carteira".
Campos da resposta-
balancenumberSaldo disponível na carteira.
-
currencystringMoeda de liquidação, USD.
- 401Chave em falta ou inválida.
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"
}
Preços e stock
Explore os mercados disponíveis, o preço exato que paga por duração e o stock em tempo real.
O objeto de preços por país
Um país e todos os pacotes que pode comprar nele. price é o montante final cobrado à sua carteira; o custo a montante nunca é revelado.
Campos-
country_codestringCódigo ISO 3166-1 alfa-2, p. ex. US.
-
country_namestringNome apresentado.
-
packages[].number_typeenumvoip ou non_voip.
-
packages[].durationenumA chave que envia para comprar: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths ou oneYear. Cada país oferece o seu próprio conjunto.
-
packages[].duration_labelstringEtiqueta legível, p. ex. "1 Mês".
-
packages[].pricenumberPreço final em USD.
-
packages[].original_pricenumber | nullO preço antes do desconto, quando se aplica.
-
packages[].updated_atnullReservado.
{
"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
Listar preços de todos os países
O catálogo completo em tempo real: uma lista de objetos de preços por país. O campo price é a tarifa final apresentada ao utilizador em USD, exatamente o que é cobrado à sua carteira.
DevolveUma lista de objetos de preços por país em data, com meta.count.
Erros- 401Chave em falta ou inválida.
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}
Obter preços de um país
Preços em tempo real de um único país. Um 404 significa que o país não tem nenhuma rota ativa neste momento: trate-o como "esgotado" temporário e não como "nunca vendido".
Parâmetros-
countryCodestring path ObrigatórioCódigo de país ISO 3166-1 alfa-2, p. ex. US, GB, CA.
Um objeto de preços por país em data.
Erros- 404Nenhuma rota ativa para esse país neste momento.
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
Verificar stock
Stock em tempo real para um país e uma duração, para poder desativar um botão de compra antes de alguém clicar nele. Omita number_type para obter todos os tipos lado a lado em types[]. Um resultado verde é um forte indicador, mas a própria compra é a verificação final.
Parâmetros-
country_codestring query ObrigatórioCódigo de país ISO 3166-1 alfa-2.
-
durationenum query OpcionalUma chave de duração de GET /pricing/{countryCode}. Omita para usar a predefinição da rota.
Um dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query OpcionalLimite a verificação a um tipo. Omita para ver todos os tipos.
Um devoipnon_voip
-
stockinteger | nullNúmeros disponíveis (somados em types[] quando number_type é omitido).
-
availablebooleanTrue quando é possível comprar, pelo menos, um número.
-
statusstringEtiqueta legível: Em stock, Esgotado, Brevemente…
-
types[]arrayApenas quando number_type é omitido: number_type, stock, available, status para cada tipo que o mercado vende.
- 422Nada à venda para essa seleção; details contém os campos de stock.
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" }
]
}
}
Números
Liste, compre, renove e cancele os seus números privados. As chamadas que movimentam dinheiro são idempotentes e seguras contra repetições.
O objeto de número
Um número da sua conta. Comprar, renovar e cancelar também devolvem um resumo financeiro em meta: charged (ou refunded), currency e wallet_balance_after.
Campos-
idintegerUtilize-o nas chamadas /numbers/{id}/…. Os webhooks enviam-no como number.rentalId.
-
phone_numberstringE.164, p. ex. +14035551234.
-
country_codestring | nullISO 3166-1 alfa-2.
-
country_namestringNome apresentado.
-
number_typeenumvoip ou non_voip.
-
statusenumactive, expired, cancelled ou refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 8601, UTC. A partir daí, o número deixa de receber SMS e não pode ser renovado.
Aliases obsoletos ainda enviados para integrações antigas: country, provider, purchased_at e expires_at (milissegundos epoch). Não dependa deles.
{
"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
Listar os seus números
Todos os números da sua conta, dos mais recentes para os mais antigos. Utilize status=expiring_soon (números ativos a menos de 10 dias de expirar) para gerir lembretes de renovação.
Parâmetros-
statusenum query OpcionalFiltro de ciclo de vida. Predefinição: all.
Um deallactiveexpiring_soonexpiredcancelled
Uma lista de objetos de número em data; meta.count e meta.status.
Erros- 401Chave em falta ou inválida.
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 obrigatório Comprar um número
Atribui um novo número privado e cobra à sua carteira num único passo atómico. Se a entrega falhar após a cobrança, esta é revertida: nunca fica a pagar sem receber nada. A resposta mostra o montante cobrado e o saldo resultante.
Parâmetros-
country_codestring body ObrigatórioUm país de GET /pricing.
-
durationenum body ObrigatórioUma chave de duração do packages[] desse país - cada país oferece o seu próprio conjunto.
Um dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body OpcionalOmita para usar a predefinição da rota.
Um devoipnon_voip -
Idempotency-Keystring header ObrigatórioUm UUID, novo em cada compra e reutilizado nas novas tentativas.
O novo objeto de número em data; meta.charged, meta.currency, meta.wallet_balance_after.
Erros- 422
insufficient_fundsA carteira não tem saldo suficiente para o preço. - 422
out_of_stockEsgotado desde a sua verificação de stock. - 422
invalid_durationDuração não disponível para este país/tipo. - 403
kyc_requiredÉ necessária primeiro a verificação de identidade. Nada foi cobrado. - 503
purchases_pausedCompras suspensas em toda a plataforma. 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 obrigatório Renovar um número
Prolonga um número com o pacote escolhido. O novo período é somado à validade atual, por isso renovar antecipadamente não faz perder nada. O preço é a tarifa atual do site, calculada por nós. Os números expirados não podem ser renovados: compre um novo.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
packageenum body OpcionalDuração da renovação. Predefinição: oneMonth. (duration é aceite como alias antigo.)
Um deoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ObrigatórioUm UUID, novo em cada renovação e reutilizado nas novas tentativas.
O objeto de número atualizado em data; meta.charged, meta.currency, meta.wallet_balance_after.
Erros- 404Não é um número da sua conta.
- 422
insufficient_fundsA carteira não tem saldo suficiente para a renovação. - 422Expirado, cancelado ou não renovável.
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 obrigatório Cancelar um número para obter reembolso
Liberta um número e reembolsa o preço total para a sua carteira. Só é permitido entre 15 e 120 minutos após a compra, enquanto o número estiver ativo e antes de ter recebido qualquer SMS. Fora destas regras, a chamada é recusada com 422 e nada muda; se for demasiado cedo, details.seconds_until_open indica quanto tempo deve esperar.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
Idempotency-Keystring header ObrigatórioUm UUID, reutilizado nas novas tentativas.
O objeto de número (status cancelled) em data; meta.refunded, meta.currency, meta.wallet_balance_after.
Erros- 404Não é um número da sua conta.
- 422Demasiado cedo (menos de 15 min), demasiado tarde (mais de 120 min), já recebeu SMS ou não está ativo.
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
Leia os SMS que os seus números recebem. Recebe o texto em bruto; a extração do código fica a seu cargo.
O objeto de mensagem SMS
Um SMS recebido, tal como devolvido por GET /numbers/{id}/sms. (GET /receive-sms utiliza uma variante em camelCase, apresentada nesse endpoint.)
Campos-
idintegerId da mensagem.
-
fromstringRemetente: um número de telefone ou um nome, como WhatsApp.
-
bodystringO texto completo da mensagem.
-
received_atstringISO 8601, UTC.
Aliases obsoletos ainda enviados: sender (= from) e message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Obter um número e os respetivos SMS
Um número com todos os SMS que recebeu, dos mais recentes para os mais antigos. Ideal para uma vista de "detalhe deste número" e para consultar periodicamente um único número enquanto espera por um código. Ids que não são seus respondem 404.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
data.number (um objeto de número) e data.messages (objetos de mensagem SMS); meta.count.
Erros- 404Não é um número da sua conta.
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
Receber SMS por número de telefone
SMS paginados por cursor de um número seu, identificado pelo número de telefone em vez do id. Ideal para caixas de entrada com muito volume. Um número que não seja seu responde 403.
Parâmetros-
phoneNumberstring query ObrigatórioE.164 ou apenas algarismos, p. ex. +14035551234. Codifique o + no URL.
-
limitinteger query OpcionalTamanho da página 1-100. Predefinição: 50.
-
cursorstring query Opcionalmeta.nextCursor da página anterior.
-
data.messages[].idintegerId da mensagem.
-
data.messages[].fromstringRemetente.
-
data.messages[].tostringO seu número.
-
data.messages[].messagestringO texto completo.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullPasse nextCursor como cursor para a página seguinte.
- 403O número não pertence à sua conta.
- 422phoneNumber em falta ou inválido.
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 privado
Uma caixa de entrada [email protected] gratuita, só de receção, para cada número privado. Um endereço por número.
O objeto de e-mail privado
A caixa de entrada associada a um número.
Campos-
addressstring | nullO endereço, ou null antes de ser obtido.
-
statusenumactive ou none.
-
unread_countintegerE-mails não lidos.
-
created_atstring | nullQuando o endereço foi obtido.
-
eligiblebooleanTrue quando o número pode obter um endereço agora.
-
linked_numberstringO número de telefone a que pertence.
-
domainstringprivnum.com
-
suggestionsstring[]Sugestões de nomes enquanto for elegível.
{
"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
Obter o e-mail privado
O endereço de um número ou, antes de ser obtido, se pode ter um e algumas sugestões de nomes.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
Um objeto de e-mail privado em data.
Erros- 404Não é um número da sua conta.
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
Verificar um nome
Verificação em tempo real de que um nome é válido e está livre antes de o obter.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
local_partstring query ObrigatórioA parte antes de @: 3-64 letras, algarismos, pontos, hífenes ou sublinhados.
-
availablebooleanTrue quando o pode obter.
-
reasonenum | nulltoo_short, too_long, invalid, reserved ou taken.
- 404Não é um número da sua conta.
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
Obter um endereço
Atribui um endereço a um número ativo. Gratuito, um por número, e um endereço obtido nunca é entregue a mais ninguém.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
local_partstring body ObrigatórioO nome que verificou.
O objeto de e-mail privado em data.
Erros- 404Não é o seu número ou ainda não tem endereço.
- 422Nome ocupado ou inválido (details.reason), o número já tem um endereço ou não está ativo.
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
Listar e-mails
Resumos dos e-mails, dos mais recentes para os mais antigos, com paginação por páginas e a contagem de não lidos no nível superior.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
pageinteger query OpcionalNúmero da página. Predefinição: 1.
-
per_pageinteger query Opcional1-100. Predefinição: 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerNo nível superior, junto a data.
- 404Não é o seu número ou ainda não tem endereço.
- 404
private_email_closedO número foi cancelado ou reembolsado.
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
Ler um e-mail
O e-mail completo (HTML e texto) com a lista de anexos. Lê-lo marca-o como lido.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
messageIdinteger path ObrigatórioId do e-mail da lista da caixa de entrada.
- 404Não é o seu número ou ainda não tem endereço.
- 404
private_email_closedO número foi cancelado ou reembolsado.
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}
Transferir um anexo
O ficheiro em bruto, com o seu próprio Content-Type e nome de ficheiro. index vem do attachments[] do e-mail.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
messageIdinteger path ObrigatórioId do e-mail da lista da caixa de entrada.
-
indexinteger path Obrigatórioattachments[].index de Ler um email.
- 404Não é o seu número ou ainda não tem endereço.
- 404
private_email_closedO número foi cancelado ou reembolsado. - 404Não existe nenhum anexo nesse índice.
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}
Eliminar um e-mail
Elimina o e-mail e os respetivos anexos.
Parâmetros-
idinteger path ObrigatórioId do número de GET /numbers.
-
messageIdinteger path ObrigatórioId do e-mail da lista da caixa de entrada.
- 404Não é o seu número ou ainda não tem endereço.
- 404
private_email_closedO número foi cancelado ou reembolsado.
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
}
IA e MCP
Deixe um assistente de IA usar diretamente a sua conta, ou dê a um agente de programação tudo o que precisa para desenvolver sobre a API.
Servidor MCP
Para além da API REST, disponibilizamos um servidor Model Context Protocol. Ligue-o ao Claude, ao ChatGPT ou ao seu editor e o assistente pode consultar preços e stock, comprar um número e ler os respetivos SMS como ferramentas nativas, sem código da sua parte. Novo no MCP? Comece pela visão geral do servidor MCP.
Endpointhttps://mcp.temp-number.com/mcp
Como funciona o início de sessão
- Adicione o URL à sua app de IA. Ela redireciona-o para a Temp Number para iniciar sessão com a sua própria conta (OAuth 2.1 com PKCE) - sem chave para copiar.
- No ecrã de consentimento, escolhe o que o assistente pode fazer. Ler o saldo, os preços, os seus números e os respetivos SMS está sempre incluído. Permitir compras - comprar, renovar e cancelar com a sua carteira - fica desativado, a menos que o assinale.
- Todas as ligações estão listadas em Painel → Servidor MCP → Apps ligadas, onde pode desligá-las a qualquer momento.
- Prefere uma chave (CI, scripts, agentes headless)? Crie uma chave MCP na mesma página e envie-a como
Authorization: Bearer <key>. As chaves MCP e as chaves da API REST não são intercambiáveis.
Ferramentas
| Ferramenta | O que faz | Requer "Permitir compras" |
|---|---|---|
get-balance | Obtém o saldo da carteira da conta autenticada e a moeda de faturação. | Não |
get-pricing | Devolve o catálogo de preços ativo para todos os países ou para um único código de país ISO. | Não |
get-inventory | Consulta a disponibilidade de inventário em tempo real para um país, uma duração e um tipo de número opcional. | Não |
purchase-number | Compra um número privado para a conta autenticada com fundos da carteira. | Sim |
list-active-numbers | Devolve os números da conta autenticada, com filtro opcional por estado. | Não |
check-sms | Obtém as mensagens SMS de um ID de número comprado que pertence à conta autenticada. | Não |
renew-number | Renova um número comprado pelo ID com um pacote de duração opcional. | Sim |
cancel-number | Cancela um número comprado pelo ID e devolve à carteira o reembolso elegível. | Sim |
Ligue a sua ferramenta de IA
Escolha a sua app. A maioria liga-se num clique: inicia sessão na Temp Number, assinala o que o assistente pode fazer e clica em Permitir.
Claude - claude.ai, desktop e telemóvel
Nada para instalar. Funciona no navegador, na app de desktop e no telemóvel.
- Clique em Adicionar ao Claude. O Claude abre com a Temp Number e o respetivo URL já preenchidos. Clique em Add.
- Clique em Connect, inicie sessão na Temp Number, escolha se o Claude pode fazer compras e clique em Permitir.
- Em qualquer chat, abra o menu + → Connectors e ative a Temp Number. Experimente: "Quanto custa um número dos EUA por um mês?"
Não vê o botão? No Claude, vá a Customize → Connectors → Add custom connector e cole o endpoint MCP. As organizações com a opção de cabeçalho de pedido do Claude podem enviar uma chave MCP como Authorization: Bearer <key> em vez de iniciar sessão.
ChatGPT
Requer ChatGPT Business, Enterprise ou Edu na web. No Business, é um administrador ou proprietário que o adiciona.
- Copie o URL do servidor abaixo e clique em Abrir ChatGPT para ir à página Plugins. O ChatGPT não tem um link que preencha isto por si.
- Clique em + → Add custom MCP server. Dê-lhe o nome Temp Number e cole o URL em Connection.
- Defina a autenticação como OAuth, aceite o aviso de risco e clique em Create as a plugin.
- Quando o ChatGPT pedir, inicie sessão na Temp Number, escolha se o ChatGPT pode fazer compras e clique em Permitir.
- Num novo chat, escreva @ e escolha Temp Number. Experimente: "Quanto custa um número dos EUA por um mês?"
https://mcp.temp-number.com/mcp
Claude Code
Adicione o servidor uma vez e depois inicie sessão a partir do Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Inicie o Claude Code e escreva
/mcp. - Escolha temp-number → Authenticate. O navegador abre-se: inicie sessão e clique em Permitir.
Usar uma chave MCP em alternativa (CI / headless)
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
Adicione o servidor e depois inicie sessão. O Codex guarda a sessão por si.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Usar uma chave MCP em alternativa (CI / headless)
Em ~/.codex/config.toml. A chave é lida a partir do ambiente, por isso o ficheiro pode ser partilhado em segurança.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Um clique e depois inicie sessão quando o Cursor pedir.
Ou adicione-o a .cursor/mcp.json (ou ~/.cursor/mcp.json). O Cursor mostra então Needs login junto ao servidor: clique, inicie sessão e clique em Permitir.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usar uma chave MCP em alternativa
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Um clique e depois inicie sessão na primeira vez que uma ferramenta for executada.
Ou adicione-o a .vscode/mcp.json - atenção que a chave é servers, não mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usar uma chave MCP em alternativa
O VS Code pede a chave uma vez e guarda-a no seu armazenamento de segredos.
{
"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
}
]
}
Qualquer outra app MCP
Windsurf, Zed, LibreChat, o seu próprio agente…
- Adicione o endpoint MCP como servidor remoto (HTTP streamable). As apps que suportam início de sessão encontram-no sozinhas em
https://mcp.temp-number.com/.well-known/oauth-protected-resourcee abrem o ecrã de consentimento da Temp Number. - As apps sem suporte de início de sessão podem enviar uma chave MCP como
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
llms.txt e prompt do agente
Está a desenvolver com um assistente de programação com IA? Dê-lhe o contexto abaixo e ele consegue integrar a API corretamente à primeira - autenticação, idempotência e limites de pedidos incluídos.
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 é um resumo em texto simples, sempre atualizado, de todos os endpoints; a especificação OpenAPI é o contrato tipado. Ambos são atualizados com a API.Recursos
O que mudou e onde obter ajuda.
Registo de alterações
Apenas alterações aditivas - nada foi removido de /v1.
-
NewMCP: inicie sessão com a sua conta Temp Number
"Add to Claude" com um clique, além de ChatGPT, Claude Code, Codex, Cursor e VS Code sem copiar nenhuma chave. Escolhe no ecrã de consentimento se a IA pode gastar.
-
DocsUma nova casa para a documentação
Início rápido, pesquisa e todos os exemplos em cURL, Node.js, Python e PHP. Os erros, limites de pedidos e reembolsos correspondem agora exatamente à API em produção.
-
Newllms.txt para todo o site
Um mapa do serviço em texto simples para assistentes de IA, com ligação para a referência da API preparada para agentes.
-
NewLigue a sua ferramenta de IA
Configuração para Claude Code, Codex, Cursor e VS Code, com ligações de instalação com um clique para Cursor e VS Code.
-
NewEspecificação OpenAPI
O contrato legível por máquina está disponível em https://api.temp-number.com/api.json.
-
ImprovedOs objetos correspondem à referência
Os números e SMS utilizam datas ISO 8601 e from/body. Os erros incluem um código legível por máquina (out_of_stock, insufficient_funds, invalid_duration). /inventory indica todos os tipos de número quando omite number_type. Os nomes de campos antigos continuam a funcionar como aliases obsoletos.
-
NewEndpoints de e-mail privado
Obtenha uma caixa de entrada [email protected] gratuita para um número, leia e-mails e transfira anexos através da API.
-
NewServidor MCP
Os agentes de IA podem consultar preços, comprar números e ler SMS como ferramentas, com uma chave MCP.
-
LaunchAPI REST pública v1
Conta, preços, inventário, ciclo de vida dos números e SMS, com autenticação por token Bearer.
Suporte
Está com dificuldades, ou encontrou algo nesta documentação que não corresponde ao que a API faz? Contacte-nos - inclua o endpoint, a hora do pedido e o corpo da resposta (nunca a sua chave de API).
Pronto para começar a desenvolver?
Crie uma chave e faça a sua primeira chamada em menos de um minuto.