API de Temp Number - Números de teléfono, SMS y OTP
Obtén números de teléfono virtuales, recibe SMS en tiempo real y automatiza la verificación OTP, desde una API REST clara o directamente desde tu asistente de IA.
https://api.temp-number.com/v1
Inicio / Desarrolladores
Introducción
La API de Temp Number se organiza en torno a recursos predecibles, usa verbos HTTP estándar y devuelve JSON en todas las respuestas. Una clave da acceso de lectura y escritura solo a tu cuenta: no hay acceso entre cuentas.
Inicio rápido
De cero a un código de verificación. Elige tu lenguaje una vez y todos los ejemplos de la página lo seguirán.
-
Crear una clave de API
En Panel → Acceso a la API, crea una clave. Solo se muestra una vez: guárdala como la variable de entorno
TEMP_NUMBER_API_KEY. -
Consulta tu saldo
Cada llamada lleva tu clave en el encabezado Authorization. Empieza con algo inofensivo: el saldo de tu monedero.
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(); -
Elige un país y comprueba el stock
GET /pricing lista todos los países con el precio exacto por duración. Después confirma el stock del que quieras.
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 un número
Envía una Idempotency-Key nueva con cada compra. Si se cae la red, reintenta con la misma clave: nunca se te cobra dos veces. Guarda data.id de la respuesta.
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(); -
Leer los SMS
Consulta el número cada pocos segundos hasta que llegue el mensaje. Recibes el texto sin procesar; extrae el código por tu cuenta.
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(); -
¿No llega el SMS? Cancela con reembolso
Entre 15 y 120 minutos después de la compra, un número que no haya recibido SMS se puede cancelar con reembolso completo a tu monedero.
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();
Autenticación
Envía tu clave de API en la cabecera estándar Authorization en cada solicitud:
Authorization: Bearer YOUR_API_KEY
- Crea claves en Acceso a la API. La clave completa se muestra una sola vez, al crearla.
- Usa una clave por integración para poder revocar una sin afectar a las demás. Al cambiar tu contraseña se revocan todas las claves.
- Una clave ausente, mal formada o revocada responde
401. Una cuenta que no ha verificado su email, o que está suspendida, responde403concodeemail_unverifiedoaccount_suspended. - Las claves REST solo funcionan en
/v1. El servidor MCP usa su propio inicio de sesión o claves MCP: consulta Servidor MCP.
URL base y versiones
Todos los endpoints están bajo el prefijo permanente /v1:
https://api.temp-number.com/v1
Los cambios aditivos (campos, endpoints o parámetros opcionales nuevos) se publican sin cambiar de versión, así que ignora los campos que no conozcas. Un cambio incompatible se publicaría bajo /v2; tu integración nunca se migra sin avisar. El contrato legible por máquina es la especificación OpenAPI.
Solicitudes y respuestas
- Envía cuerpos JSON con
Content-Type: application/jsonyAccept: application/jsonen cada solicitud. - Éxito:
{ "success": true, "data": …, "meta": {…} }.metaincluye recuentos, paginación y resúmenes de importes. - Errores:
{ "success": false, "message": "…", "code": "…" }. Decide segúncode; el mensaje es para personas. Consulta Errores. - Las fechas y horas siguen ISO 8601. Los importes están en USD con dos decimales: siempre el precio que pagas.
- Algunos objetos aún incluyen nombres de campo antiguos para las integraciones existentes (marcados como obsoletos en la referencia). El código nuevo debe ignorarlos.
Errores
Los errores usan códigos de estado HTTP estándar. Los errores de negocio incluyen un code estable y legible por máquina; algunos incluyen details con más 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 | Qué hacer |
|---|---|---|---|
| 400 | - | Falta el encabezado Idempotency-Key o tiene un formato incorrecto al comprar, renovar o cancelar. Cuerpo: {"error": "Missing Idempotency-Key header."} | Envía un UUID en Idempotency-Key. |
| 401 | - | Sin token Bearer, con uno mal formado o con una clave revocada. | Revisa el encabezado Authorization; crea una clave nueva si se revocó. |
| 403 | email_unverified |
La cuenta aún no ha verificado su dirección de correo. | Verifica el correo en el sitio web y vuelve a intentarlo. |
| 403 | account_suspended |
La cuenta está suspendida. | Contacta con soporte. |
| 403 | kyc_required |
La cuenta debe verificar su identidad antes de comprar números nuevos. No se ha cobrado nada; las renovaciones siguen funcionando. | Completa la verificación de identidad en los ajustes de la cuenta y vuelve a intentarlo. |
| 403 | - | La clave no tiene acceso a la API (por ejemplo, una clave MCP), o se consultó en GET /receive-sms un número de otra cuenta. | Usa una clave de API REST; consulta solo tus propios números. |
| 404 | - | El número, mensaje o país no está en tu cuenta o no está a la venta en este momento. Los ids de otras cuentas también responden 404. | Vuelve a listar con GET /numbers o GET /pricing. |
| 404 | private_email_closed |
La bandeja de entrada privada está cerrada porque su número se canceló o se reembolsó. | No hay nada que reintentar. |
| 409 | - | La Idempotency-Key ya se usó con un cuerpo distinto, o la primera solicitud con ella aún está en curso. | Usa una clave nueva para una solicitud nueva; espera y reintenta la que está en curso. |
| 422 | insufficient_funds |
El monedero no cubre el precio. | Recarga el monedero y vuelve a intentarlo. |
| 422 | out_of_stock |
El mercado se agotó entre tu consulta de precio y la compra. | Vuelve a consultar GET /inventory y elige otra duración u otro tipo. |
| 422 | invalid_duration |
La duración no está a la venta para ese país y tipo de número. | Vuelve a obtener GET /pricing/{countryCode}. |
| 422 | - | La validación falló (un objeto `errors` indica cada campo) o una regla rechazó la acción, por ejemplo cancelar fuera del plazo de reembolso. | Lee `message`; corrige la solicitud en lugar de reintentarla. |
| 429 | - | Límite de solicitudes alcanzado. | Espera lo que indique el encabezado Retry-After y reintenta con espera progresiva. |
| 503 | purchases_paused |
Las nuevas compras están pausadas en toda la plataforma. No se ha cobrado nada; las renovaciones y cancelaciones siguen funcionando. | Reintenta después de Retry-After (60 s). |
| 5xx | - | Algo falló por nuestra parte. | Reintenta con la MISMA Idempotency-Key: nunca se te cobrará dos veces. |
Límites de uso
Los límites se aplican por clave, y las llamadas que mueven dinero tienen además un límite más estricto por cuenta:
| Se aplica a | Límite | Se contabiliza |
|---|---|---|
| Todos los endpoints | 60 / minuto | por clave de API |
| Comprar, renovar, cancelar | 10 / minuto | por cuenta, además de lo anterior |
| GET /receive-sms | 60 / minuto | por clave de API |
| GET /receive-sms | 30 / minuto | por clave de API y número de teléfono |
| GET /receive-sms | 30 / minuto | por dirección IP |
Si superas un límite recibes 429 con una cabecera Retry-After (en segundos). Espera al menos ese tiempo y luego reintenta con retroceso y variación aleatoria. Las respuestas también incluyen X-RateLimit-Limit y X-RateLimit-Remaining.
Idempotencia
POST /numbers/buy, /renew y /cancel requieren una cabecera Idempotency-Key: un UUID que creas para cada acción nueva. Si se cae la red, envía la misma solicitud con la misma clave: recibirás la respuesta original (marcada con X-Idempotency-Replayed: true) y nunca se te cobrará dos veces.
- Clave ausente:
400. Las claves tienen hasta 128 caracteres entre letras, dígitos y- _ . : - Misma clave con otro cuerpo:
409. Misma clave mientras la primera solicitud sigue en curso:409; espera un momento y vuelve a intentarlo. - Las claves se recuerdan por cuenta y endpoint. Nunca reutilices una para otra compra.
Paginación
GET /receive-sms usa paginación por cursor, de más reciente a más antiguo. Lee meta.hasMore; mientras sea true, envía meta.nextCursor como cursor con el mismo phoneNumber. Los cursores son opacos: no los construyas ni los modifiques.
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9
Las listas que por naturaleza son pequeñas (/numbers, /pricing) devuelven todo en una sola respuesta; la bandeja privada usa page y per_page.
Uso aceptable
La API está pensada para desarrolladores: flujos de verificación y OTP, registro automatizado de usuarios, QA y pruebas de sistemas, y cualquier producto que necesite SMS entrantes o números de teléfono a escala.
- Úsala solo para verificaciones legítimas, desarrollo y pruebas.
- Nada de estafas, spam, fraude ni engaños. Si se usan números para estafas u otras actividades abusivas, la cuenta será bloqueada de inmediato y sin previo aviso, se cancelarán los números asociados y no procederá ningún reembolso.
- No apto para cuentas reguladas o vinculadas a la identidad. Nuestros números temporales compartidos no admiten la verificación por SMS de servicios bancarios, de pagos, de criptomonedas, gubernamentales u otros que verifican tu identidad legal (KYC/AML); usa tu número de móvil personal para ellos.
Referencia de la API
Todos los endpoints activos de /v1. Las solicitudes aparecen a la derecha en tu lenguaje; las respuestas tienen la estructura real.
Cuenta
Consulta el saldo de tu monedero y la moneda de liquidación.
/v1/account
Obtener el saldo de la cuenta
Devuelve el saldo disponible del monedero y su moneda. Consúltalo antes de una compra para poder detenerte a tiempo con un mensaje claro de "recarga".
Campos de la respuesta-
balancenumberSaldo disponible del monedero.
-
currencystringMoneda de liquidación, USD.
- 401Clave ausente o no vá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"
}
Precios y stock
Explora los mercados activos, el precio exacto que pagas por cada duración y el stock en tiempo real.
El objeto de precios por país
Un país y todos los paquetes que puedes comprar allí. price es el importe final que se cobra a tu monedero; el coste del proveedor nunca se expone.
Campos-
country_codestringCódigo ISO 3166-1 alfa-2, p. ej. US.
-
country_namestringNombre visible.
-
packages[].number_typeenumvoip o non_voip.
-
packages[].durationenumLa clave que envías para comprar: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths u oneYear. Cada país ofrece su propio conjunto.
-
packages[].duration_labelstringEtiqueta legible, p. ej. "1 mes".
-
packages[].pricenumberPrecio final en USD.
-
packages[].original_pricenumber | nullEl precio antes del descuento, cuando se aplica uno.
-
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 precios de todos los países
El catálogo completo en vivo: una lista de objetos de precios por país. El campo price es la tarifa final para el usuario en USD, exactamente lo que se cobra a tu monedero.
DevuelveUna lista de objetos de precios por país en data, con meta.count.
Errores- 401Clave ausente o no vá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}
Obtener precios de un país
Precios en vivo de un solo país. Un 404 significa que el país no tiene ninguna ruta activa ahora mismo: trátalo como un "agotado" temporal, no como "nunca a la venta".
Parámetros-
countryCodestring path ObligatorioCódigo de país ISO 3166-1 alfa-2, p. ej. US, GB, CA.
Un objeto de precios de país en data.
Errores- 404No hay ninguna ruta activa para ese país en este 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
Comprobar stock
Stock en tiempo real para un país y una duración, para que puedas desactivar un botón de compra antes de que nadie haga clic. Omite number_type para obtener todos los tipos juntos en types[]. Un resultado en verde es una señal fiable, pero la compra en sí es la comprobación definitiva.
Parámetros-
country_codestring query ObligatorioCódigo de país ISO 3166-1 alfa-2.
-
durationenum query OpcionalUna clave de duración de GET /pricing/{countryCode}. Omítela para usar la predeterminada de la ruta.
Uno dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query OpcionalLimita la comprobación a un tipo. Omítelo para ver todos los tipos.
Uno devoipnon_voip
-
stockinteger | nullNúmeros disponibles (sumados sobre types[] cuando se omite number_type).
-
availablebooleanTrue cuando se puede comprar al menos un número.
-
statusstringEtiqueta legible: En stock, Agotado, Próximamente…
-
types[]arraySolo cuando se omite number_type: number_type, stock, available y status por cada tipo que vende el mercado.
- 422No hay nada a la venta para esa selección; details incluye los 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
Lista, compra, renueva y cancela tus números privados. Las llamadas que mueven dinero son idempotentes y seguras ante reintentos.
El objeto de número
Un número de tu cuenta. Comprar, renovar y cancelar también devuelven un resumen económico en meta: charged (o refunded), currency y wallet_balance_after.
Campos-
idintegerÚsalo en las llamadas /numbers/{id}/…. Los webhooks lo envían como number.rentalId.
-
phone_numberstringE.164, p. ej. +14035551234.
-
country_codestring | nullISO 3166-1 alfa-2.
-
country_namestringNombre visible.
-
number_typeenumvoip o non_voip.
-
statusenumactive, expired, cancelled o refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 8601, UTC. A partir de entonces el número deja de recibir SMS y no se puede renovar.
Alias obsoletos que se siguen enviando para integraciones antiguas: country, provider, purchased_at y expires_at (milisegundos epoch). No los uses en desarrollos nuevos.
{
"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 tus números
Todos los números de tu cuenta, del más reciente al más antiguo. Usa status=expiring_soon (números activos a 10 días o menos de caducar) para gestionar los recordatorios de renovación.
Parámetros-
statusenum query OpcionalFiltro de ciclo de vida. Por defecto all.
Uno deallactiveexpiring_soonexpiredcancelled
Una lista de objetos de número en data; meta.count y meta.status.
Errores- 401Clave ausente o no vá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 obligatoria Comprar un número
Asigna un nuevo número privado y cobra tu monedero en un solo paso atómico. Si la entrega falla después del cobro, el cargo se revierte: nunca acabas pagando sin recibir nada. La respuesta muestra el importe cobrado y tu saldo posterior.
Parámetros-
country_codestring body ObligatorioUn país de GET /pricing.
-
durationenum body ObligatorioUna clave de duración del packages[] de ese país; cada país ofrece su propio conjunto.
Uno dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body OpcionalOmítelo para usar el valor predeterminado de la ruta.
Uno devoipnon_voip -
Idempotency-Keystring header ObligatorioUn UUID, nuevo en cada compra y reutilizado en los reintentos.
El nuevo objeto de número en data; meta.charged, meta.currency, meta.wallet_balance_after.
Errores- 422
insufficient_fundsEl monedero no cubre el precio. - 422
out_of_stockSe agotó después de tu comprobación de stock. - 422
invalid_durationDuración no disponible para este país/tipo. - 403
kyc_requiredPrimero se necesita verificar la identidad. No se ha cobrado nada. - 503
purchases_pausedCompras pausadas en toda la 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 obligatoria Renovar un número
Amplía un número con el paquete elegido. El nuevo plazo se suma al vencimiento actual, así que renovar antes no te hace perder nada. El precio es la tarifa actual del sitio, calculada por nuestra parte. Los números caducados no se pueden renovar: compra uno nuevo.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
packageenum body OpcionalDuración de la renovación. Por defecto oneMonth. (duration se acepta como alias heredado).
Uno deoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ObligatorioUn UUID, nuevo en cada renovación y reutilizado en los reintentos.
El objeto de número actualizado en data; meta.charged, meta.currency, meta.wallet_balance_after.
Errores- 404No es un número de tu cuenta.
- 422
insufficient_fundsEl monedero no cubre la renovación. - 422Caducado, cancelado o no renovable.
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 obligatoria Cancelar un número con reembolso
Libera un número y reembolsa su precio completo a tu monedero. Solo se permite entre 15 y 120 minutos después de la compra, mientras el número esté activo y antes de que haya recibido algún SMS. Fuera de esas condiciones, la llamada se rechaza con 422 y no cambia nada; si es demasiado pronto, details.seconds_until_open indica cuánto esperar.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
Idempotency-Keystring header ObligatorioUn UUID, reutilizado en los reintentos.
El objeto de número (status cancelled) en data; meta.refunded, meta.currency, meta.wallet_balance_after.
Errores- 404No es un número de tu cuenta.
- 422Demasiado pronto (menos de 15 min), demasiado tarde (más de 120 min), ya ha recibido SMS o no está activo.
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
Lee los SMS que reciben tus números. Recibes el texto sin procesar; extraer el código depende de ti.
El objeto de mensaje SMS
Un SMS recibido, tal como lo devuelve GET /numbers/{id}/sms. (GET /receive-sms usa una variante en camelCase, que se muestra en ese endpoint).
Campos-
idintegerId del mensaje.
-
fromstringRemitente: un número de teléfono o un nombre como WhatsApp.
-
bodystringEl texto completo del mensaje.
-
received_atstringISO 8601, UTC.
Alias obsoletos que se siguen enviando: sender (= from) y message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Obtener un número y sus SMS
Un número junto con todos los SMS que ha recibido, del más reciente al más antiguo. Ideal para una vista de "detalle de este número" y para consultar un solo número mientras esperas un código. Los ids que no son tuyos responden 404.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
data.number (un objeto de número) y data.messages (objetos de mensaje SMS); meta.count.
Errores- 404No es un número de tu cuenta.
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
Recibir SMS por número de teléfono
SMS con paginación por cursor de un número tuyo, identificado por su número de teléfono en lugar de su id. Ideal para bandejas de entrada con mucho volumen. Un número que no es tuyo responde 403.
Parámetros-
phoneNumberstring query ObligatorioE.164 o solo dígitos, p. ej. +14035551234. Codifica el + en la URL.
-
limitinteger query OpcionalTamaño de página 1-100. Por defecto 50.
-
cursorstring query Opcionalmeta.nextCursor de la página anterior.
-
data.messages[].idintegerId del mensaje.
-
data.messages[].fromstringRemitente.
-
data.messages[].tostringTu número.
-
data.messages[].messagestringEl texto completo.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullPasa nextCursor como cursor para obtener la página siguiente.
- 403El número no está en tu cuenta.
- 422phoneNumber falta o no es vá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"
}
}
Correo privado
Una bandeja de entrada gratuita, solo de recepción, [email protected] para cada número privado. Una dirección por número.
El objeto de correo privado
La bandeja de entrada asociada a un número.
Campos-
addressstring | nullLa dirección, o null antes de reclamarla.
-
statusenumactive o none.
-
unread_countintegerCorreos no leídos.
-
created_atstring | nullCuándo se reclamó la dirección.
-
eligiblebooleanTrue cuando el número puede reclamar una dirección ahora.
-
linked_numberstringEl número de teléfono al que pertenece.
-
domainstringprivnum.com
-
suggestionsstring[]Sugerencias de nombre mientras sea apto.
{
"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
Obtener el correo privado
La dirección de un número o, antes de reclamarla, si puede tener una y algunas sugerencias de nombre.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
Un objeto de correo privado en data.
Errores- 404No es un número de tu cuenta.
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
Comprobar un nombre
Comprobación en vivo de que un nombre es válido y está libre antes de reclamarlo.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
local_partstring query ObligatorioLa parte antes de @: de 3 a 64 letras, números, puntos, guiones o guiones bajos.
-
availablebooleanTrue cuando puedes reclamarlo.
-
reasonenum | nulltoo_short, too_long, invalid, reserved o taken.
- 404No es un número de tu cuenta.
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
Reclamar una dirección
Asigna su dirección a un número activo. Gratis, una por número, y una dirección reclamada nunca se entrega a nadie más.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
local_partstring body ObligatorioEl nombre que comprobaste.
El objeto de correo privado en data.
Errores- 404No es tu número o todavía no tiene dirección.
- 422Nombre ocupado o no válido (details.reason), el número ya tiene una dirección o no está activo.
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 correos
Resúmenes de correos, del más reciente al más antiguo, con paginación por páginas y el recuento de no leídos en el nivel superior.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
pageinteger query OpcionalNúmero de página. Por defecto 1.
-
per_pageinteger query Opcional1-100. Por defecto 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerNivel superior, junto a data.
- 404No es tu número o todavía no tiene dirección.
- 404
private_email_closedEl número se canceló o se reembolsó.
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
Leer un correo
El correo completo (HTML y texto) con su lista de adjuntos. Al leerlo se marca como leído.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
messageIdinteger path ObligatorioId del correo de la lista de la bandeja de entrada.
- 404No es tu número o todavía no tiene dirección.
- 404
private_email_closedEl número se canceló o se reembolsó.
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}
Descargar un adjunto
El archivo sin procesar, con su propio Content-Type y nombre de archivo. index procede del attachments[] del correo.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
messageIdinteger path ObligatorioId del correo de la lista de la bandeja de entrada.
-
indexinteger path Obligatorioattachments[].index de Leer un correo.
- 404No es tu número o todavía no tiene dirección.
- 404
private_email_closedEl número se canceló o se reembolsó. - 404No hay ningún adjunto en ese í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 un correo
Elimina el correo y sus adjuntos.
Parámetros-
idinteger path ObligatorioId del número de GET /numbers.
-
messageIdinteger path ObligatorioId del correo de la lista de la bandeja de entrada.
- 404No es tu número o todavía no tiene dirección.
- 404
private_email_closedEl número se canceló o se reembolsó.
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 y MCP
Deja que un asistente de IA use tu cuenta directamente o dale a un agente de programación todo lo que necesita para desarrollar sobre la API.
Servidor MCP
Junto a la API REST ofrecemos un servidor Model Context Protocol. Conéctalo a Claude, ChatGPT o tu editor y el asistente podrá consultar precios y disponibilidad, comprar un número y leer sus SMS como herramientas nativas, sin que tengas que escribir código. ¿Nuevo en MCP? Empieza por la presentación del servidor MCP.
Endpointhttps://mcp.temp-number.com/mcp
Cómo funciona el inicio de sesión
- Añade la URL a tu app de IA. Te enviará a Temp Number para iniciar sesión con tu propia cuenta (OAuth 2.1 con PKCE), sin claves que copiar.
- En la pantalla de autorización eliges qué puede hacer el asistente. Consultar el saldo, los precios, tus números y sus SMS siempre está incluido. Permitir compras (comprar, renovar y cancelar con tu monedero) está desactivado a menos que lo marques.
- Todas las conexiones aparecen en Panel → Servidor MCP → Apps conectadas, donde puedes desconectarlas cuando quieras.
- ¿Prefieres una clave (CI, scripts, agentes sin interfaz)? Crea una clave MCP en la misma página y envíala como
Authorization: Bearer <key>. Las claves MCP y las claves de la API REST no son intercambiables.
Herramientas
| Herramienta | Qué hace | Requiere "Permitir compras" |
|---|---|---|
get-balance | Obtiene el saldo del monedero y la moneda de facturación de la cuenta autenticada. | No |
get-pricing | Devuelve el catálogo de precios activo para todos los países o para un solo código de país ISO. | No |
get-inventory | Consulta la disponibilidad de inventario en tiempo real para un país, una duración y un tipo de número opcional. | No |
purchase-number | Compra un número privado para la cuenta autenticada con fondos del monedero. | Sí |
list-active-numbers | Devuelve los números de la cuenta autenticada, con filtro opcional por estado. | No |
check-sms | Obtiene los mensajes SMS de un ID de número comprado que pertenezca a la cuenta autenticada. | No |
renew-number | Renueva un número comprado por ID con un paquete de duración opcional. | Sí |
cancel-number | Cancela un número comprado por ID y devuelve el reembolso al monedero que corresponda. | Sí |
Conecta tu herramienta de IA
Elige tu app. La mayoría se conecta con un clic: inicias sesión en Temp Number, marcas lo que puede hacer el asistente y haces clic en Allow.
Claude: claude.ai, escritorio y móvil
No hay nada que instalar. Funciona en el navegador, en la app de escritorio y en el móvil.
- Haz clic en Añadir a Claude. Claude se abrirá con Temp Number y su URL ya rellenados. Haz clic en Add.
- Haz clic en Connect, inicia sesión en Temp Number, elige si Claude puede hacer compras y haz clic en Allow.
- En cualquier chat, abre el menú + → Connectors y activa Temp Number. Prueba: "¿Cuánto cuesta un número de EE. UU. durante un mes?"
¿No ves el botón? En Claude ve a Customize → Connectors → Add custom connector y pega el endpoint MCP. Las organizaciones que tengan la opción de cabecera de solicitud de Claude pueden enviar una clave MCP como Authorization: Bearer <key> en lugar de iniciar sesión.
ChatGPT
Requiere ChatGPT Business, Enterprise o Edu en la web. En Business, lo añade un administrador o propietario.
- Copia la URL del servidor de abajo y luego haz clic en Abrir ChatGPT para ir a su página de Plugins. ChatGPT no tiene un enlace que lo rellene por ti.
- Haz clic en + → Add custom MCP server. Llámalo Temp Number y pega la URL en Connection.
- Configura la autenticación como OAuth, acepta el aviso de riesgo y haz clic en Create as a plugin.
- Cuando ChatGPT te lo pida, inicia sesión en Temp Number, elige si ChatGPT puede hacer compras y haz clic en Allow.
- En un chat nuevo, escribe @ y elige Temp Number. Prueba: "¿Cuánto cuesta un número de EE. UU. durante un mes?"
https://mcp.temp-number.com/mcp
Claude Code
Añade el servidor una vez y luego inicia sesión desde Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Inicia Claude Code y escribe
/mcp. - Elige temp-number → Authenticate. Se abrirá tu navegador: inicia sesión y haz clic en Allow.
Usar una clave MCP en su lugar (CI / sin interfaz)
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
Añade el servidor y luego inicia sesión. Codex guarda la sesión por ti.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Usar una clave MCP en su lugar (CI / sin interfaz)
En ~/.codex/config.toml. La clave se lee del entorno, así que puedes compartir el archivo sin riesgo.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Un clic y, después, inicia sesión cuando Cursor te lo pida.
O añádelo a .cursor/mcp.json (o a ~/.cursor/mcp.json). Cursor mostrará entonces Needs login junto al servidor: haz clic, inicia sesión y pulsa Allow.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usar una clave MCP en su lugar
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Un clic y, después, inicia sesión la primera vez que se ejecute una herramienta.
O añádelo a .vscode/mcp.json; ten en cuenta que la clave es servers, no mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Usar una clave MCP en su lugar
VS Code te pide la clave una vez y la guarda en su almacenamiento de secretos.
{
"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
}
]
}
Cualquier otra app MCP
Windsurf, Zed, LibreChat, tu propio agente…
- Añade el endpoint MCP como servidor remoto (HTTP transmitible). Las apps compatibles con el inicio de sesión lo encuentran por sí solas en
https://mcp.temp-number.com/.well-known/oauth-protected-resourcey abren la pantalla de autorización de Temp Number. - Las apps sin inicio de sesión pueden enviar una clave MCP como
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
llms.txt y prompt para agentes
¿Desarrollas con un asistente de programación con IA? Dale el contexto de abajo y podrá integrar la API correctamente a la primera, con autenticación, idempotencia y límites de uso incluidos.
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 es un resumen en texto plano, siempre actualizado, de todos los endpoints; la especificación OpenAPI es el contrato tipado. Ambos se actualizan con la API.Recursos
Qué ha cambiado y dónde obtener ayuda.
Registro de cambios
Solo cambios aditivos: no se ha eliminado nada de /v1.
-
NewMCP: inicia sesión con tu cuenta de Temp Number
"Add to Claude" con un clic, además de ChatGPT, Claude Code, Codex, Cursor y VS Code sin copiar ninguna clave. En la pantalla de consentimiento eliges si la IA puede gastar.
-
DocsUn nuevo hogar para la documentación
Guía rápida, búsqueda y todos los ejemplos en cURL, Node.js, Python y PHP. Los errores, los límites de solicitudes y los reembolsos ahora coinciden exactamente con la API en vivo.
-
Newllms.txt de todo el sitio
Un mapa en texto plano del servicio para asistentes de IA, con enlace a la referencia de la API preparada para agentes.
-
NewConecta tu herramienta de IA
Configuración para Claude Code, Codex, Cursor y VS Code, con enlaces de instalación con un clic para Cursor y VS Code.
-
NewEspecificación OpenAPI
El contrato legible por máquina se sirve en https://api.temp-number.com/api.json.
-
ImprovedLos objetos coinciden con la referencia
Los números y los SMS usan fechas ISO 8601 y from/body. Los errores incluyen un código legible por máquina (out_of_stock, insufficient_funds, invalid_duration). /inventory informa de todos los tipos de número cuando omites number_type. Los nombres de campo antiguos siguen funcionando como alias obsoletos.
-
NewEndpoints de correo privado
Reclama una bandeja de entrada gratuita [email protected] para un número, lee el correo y descarga los adjuntos mediante la API.
-
NewServidor MCP
Los agentes de IA pueden consultar precios, comprar números y leer SMS como herramientas, usando una clave MCP.
-
LaunchAPI REST pública v1
Cuenta, precios, inventario, el ciclo de vida del número y SMS, con autenticación por token Bearer.
Soporte
¿Te has atascado o has encontrado algo en esta documentación que no coincide con lo que hace la API? Contáctanos e incluye el endpoint, la hora de la solicitud y el cuerpo de la respuesta (nunca tu clave de API).
¿Listo para empezar a construir?
Crea una clave y haz tu primera llamada en menos de un minuto.