Plataforma para desarrolladores

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.

REST · JSON MCP para agentes de IA cURL · Node.js · Python · PHP
URL BASE 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.

ProtocoloHTTPS · JSON
AutenticaciónClave Bearer
Versiónv1 (estable)
Endpoints17 activos

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.

  1. 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.

  2. 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"
  3. 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"
  4. 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"}'
  5. 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"
  6. ¿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)"

Autenticación

Envía tu clave de API en la cabecera estándar Authorization en cada solicitud:

http
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, responde 403 con code email_unverified o account_suspended.
  • Las claves REST solo funcionan en /v1. El servidor MCP usa su propio inicio de sesión o claves MCP: consulta Servidor MCP.
Trata tu clave como una contraseña. Guárdala en tu servidor, nunca en una página web ni en una app móvil. Cámbiala de inmediato si alguna vez se registró en logs, se subió a un repositorio o se compartió.

URL base y versiones

Todos los endpoints están bajo el prefijo permanente /v1:

URL base
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/json y Accept: application/json en cada solicitud.
  • Éxito: { "success": true, "data": …, "meta": {…} }. meta incluye recuentos, paginación y resúmenes de importes.
  • Errores: { "success": false, "message": "…", "code": "…" }. Decide según code; 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.
Las respuestas nunca mencionan a un proveedor externo ni muestran el coste mayorista. El único precio que ves es el que se cobra a tu monedero, así que puedes mostrarlo a tus propios usuarios.

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.

422 · error de negocio
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · error de validación
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
EstadocodeSignificadoQué 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 aLímiteSe contabiliza
Todos los endpoints60 / minutopor clave de API
Comprar, renovar, cancelar10 / minutopor cuenta, además de lo anterior
GET /receive-sms60 / minutopor clave de API
GET /receive-sms30 / minutopor clave de API y número de teléfono
GET /receive-sms30 / minutopor 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.

¿Esperando un SMS? Consulta cada número como máximo una vez cada 5 segundos.

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.

página siguiente
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.
Vigilamos los usos abusivos. Las condiciones completas están en nuestros Términos del servicio.

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.

GET /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
  • balancenumber

    Saldo disponible del monedero.

  • currencystring

    Moneda de liquidación, USD.

Errores
  • 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"
Respuesta
{
  "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_codestring

    Código ISO 3166-1 alfa-2, p. ej. US.

  • country_namestring

    Nombre visible.

  • packages[].number_typeenum

    voip o non_voip.

  • packages[].durationenum

    La clave que envías para comprar: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths u oneYear. Cada país ofrece su propio conjunto.

  • packages[].duration_labelstring

    Etiqueta legible, p. ej. "1 mes".

  • packages[].pricenumber

    Precio final en USD.

  • packages[].original_pricenumber | null

    El precio antes del descuento, cuando se aplica uno.

  • packages[].updated_atnull

    Reservado.

objeto
{
  "country_code": "US",
  "country_name": "United States",
  "packages": [
    {
      "number_type": "voip",
      "duration": "oneMonth",
      "duration_label": "1 Month",
      "price": 4.99,
      "original_price": 5.99,
      "updated_at": null
    }
  ]
}
GET /v1/pricing

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.

Devuelve

Una 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"
Respuesta
{
  "success": true,
  "data": [
    {
      "country_code": "US",
      "country_name": "United States",
      "packages": [
        {
          "number_type": "voip",
          "duration": "oneMonth",
          "duration_label": "1 Month",
          "price": 4.99,
          "original_price": 5.99,
          "updated_at": null
        },
        {
          "number_type": "voip",
          "duration": "threeMonths",
          "duration_label": "3 Months",
          "price": 12.99,
          "original_price": null,
          "updated_at": null
        }
      ]
    }
  ],
  "meta": { "count": 1 }
}
GET /v1/pricing/{countryCode}

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
  • countryCode string path Obligatorio

    Código de país ISO 3166-1 alfa-2, p. ej. US, GB, CA.

Devuelve

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"
Respuesta
{
  "success": true,
  "data": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "packages": [
      {
        "number_type": "voip",
        "duration": "oneMonth",
        "duration_label": "1 Month",
        "price": 5.49,
        "original_price": null,
        "updated_at": null
      }
    ]
  }
}
GET /v1/inventory

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_code string query Obligatorio

    Código de país ISO 3166-1 alfa-2.

  • duration enum query Opcional

    Una clave de duración de GET /pricing/{countryCode}. Omítela para usar la predeterminada de la ruta.

    Uno de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query Opcional

    Limita la comprobación a un tipo. Omítelo para ver todos los tipos.

    Uno de voipnon_voip
Campos de la respuesta
  • stockinteger | null

    Números disponibles (sumados sobre types[] cuando se omite number_type).

  • availableboolean

    True cuando se puede comprar al menos un número.

  • statusstring

    Etiqueta legible: En stock, Agotado, Próximamente…

  • types[]array

    Solo cuando se omite number_type: number_type, stock, available y status por cada tipo que vende el mercado.

Errores
  • 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"
Respuesta
{
  "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_numberstring

    E.164, p. ej. +14035551234.

  • country_codestring | null

    ISO 3166-1 alfa-2.

  • country_namestring

    Nombre visible.

  • number_typeenum

    voip o non_voip.

  • statusenum

    active, expired, cancelled o refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 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.

objeto
{
  "id": 1482,
  "phone_number": "+14035551234",
  "country_code": "US",
  "country_name": "United States",
  "number_type": "voip",
  "status": "active",
  "purchase_date": "2026-05-13T17:42:09Z",
  "expire_date": "2026-06-13T17:42:09Z"
}
GET /v1/numbers

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
  • status enum query Opcional

    Filtro de ciclo de vida. Por defecto all.

    Uno de allactiveexpiring_soonexpiredcancelled
Devuelve

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"
Respuesta
{
  "success": true,
  "data": [
    {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    }
  ],
  "meta": { "count": 1, "status": "expiring_soon" }
}
POST /v1/numbers/buy Idempotency-Key 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_code string body Obligatorio

    Un país de GET /pricing.

  • duration enum body Obligatorio

    Una clave de duración del packages[] de ese país; cada país ofrece su propio conjunto.

    Uno de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body Opcional

    Omítelo para usar el valor predeterminado de la ruta.

    Uno de voipnon_voip
  • Idempotency-Key string header Obligatorio

    Un UUID, nuevo en cada compra y reutilizado en los reintentos.

Devuelve

El nuevo objeto de número en data; meta.charged, meta.currency, meta.wallet_balance_after.

Errores
  • 422insufficient_fundsEl monedero no cubre el precio.
  • 422out_of_stockSe agotó después de tu comprobación de stock.
  • 422invalid_durationDuración no disponible para este país/tipo.
  • 403kyc_requiredPrimero se necesita verificar la identidad. No se ha cobrado nada.
  • 503purchases_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"}'
Respuesta
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "charged": 4.99,
    "currency": "USD",
    "wallet_balance_after": 119.51
  }
}
POST /v1/numbers/{id}/renew Idempotency-Key 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
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • package enum body Opcional

    Duración de la renovación. Por defecto oneMonth. (duration se acepta como alias heredado).

    Uno de oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header Obligatorio

    Un UUID, nuevo en cada renovación y reutilizado en los reintentos.

Devuelve

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.
  • 422insufficient_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"}'
Respuesta
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-09-13T17:42:09Z"
  },
  "meta": {
    "charged": 12.99,
    "currency": "USD",
    "wallet_balance_after": 106.52
  }
}
POST /v1/numbers/{id}/cancel Idempotency-Key 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
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • Idempotency-Key string header Obligatorio

    Un UUID, reutilizado en los reintentos.

Devuelve

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)"
Respuesta
{
  "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
  • idinteger

    Id del mensaje.

  • fromstring

    Remitente: un número de teléfono o un nombre como WhatsApp.

  • bodystring

    El texto completo del mensaje.

  • received_atstring

    ISO 8601, UTC.

Alias obsoletos que se siguen enviando: sender (= from) y message (= body).

objeto
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /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
  • id integer path Obligatorio

    Id del número de GET /numbers.

Devuelve

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"
Respuesta
{
  "success": true,
  "data": {
    "number": {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    },
    "messages": [
      {
        "id": 9912,
        "from": "+18005550199",
        "body": "Your code is 432901",
        "received_at": "2026-05-13T17:43:14Z"
      }
    ]
  },
  "meta": { "count": 1 }
}
GET /v1/receive-sms

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
  • phoneNumber string query Obligatorio

    E.164 o solo dígitos, p. ej. +14035551234. Codifica el + en la URL.

  • limit integer query Opcional

    Tamaño de página 1-100. Por defecto 50.

  • cursor string query Opcional

    meta.nextCursor de la página anterior.

Campos de la respuesta
  • data.messages[].idinteger

    Id del mensaje.

  • data.messages[].fromstring

    Remitente.

  • data.messages[].tostring

    Tu número.

  • data.messages[].messagestring

    El texto completo.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    Pasa nextCursor como cursor para obtener la página siguiente.

Errores
  • 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"
Respuesta
{
  "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 | null

    La dirección, o null antes de reclamarla.

  • statusenum

    active o none.

  • unread_countinteger

    Correos no leídos.

  • created_atstring | null

    Cuándo se reclamó la dirección.

  • eligibleboolean

    True cuando el número puede reclamar una dirección ahora.

  • linked_numberstring

    El número de teléfono al que pertenece.

  • domainstring

    privnum.com

  • suggestionsstring[]

    Sugerencias de nombre mientras sea apto.

objeto
{
  "address": "[email protected]",
  "status": "active",
  "unread_count": 2,
  "created_at": "2026-07-03T10:15:00+00:00",
  "eligible": false,
  "linked_number": "+14035551234",
  "domain": "privnum.com",
  "suggestions": []
}
GET /v1/numbers/{id}/private-email

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
  • id integer path Obligatorio

    Id del número de GET /numbers.

Devuelve

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"
Respuesta
{
  "success": true,
  "data": {
    "address": null,
    "status": "none",
    "unread_count": 0,
    "created_at": null,
    "eligible": true,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": ["alex.smith", "alex.smith42"]
  }
}
GET /v1/numbers/{id}/private-email/availability

Comprobar un nombre

Comprobación en vivo de que un nombre es válido y está libre antes de reclamarlo.

Parámetros
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • local_part string query Obligatorio

    La parte antes de @: de 3 a 64 letras, números, puntos, guiones o guiones bajos.

Campos de la respuesta
  • availableboolean

    True cuando puedes reclamarlo.

  • reasonenum | null

    too_short, too_long, invalid, reserved o taken.

Errores
  • 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"
Respuesta
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /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
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • local_part string body Obligatorio

    El nombre que comprobaste.

Devuelve

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"}'
Respuesta
{
  "success": true,
  "data": {
    "address": "[email protected]",
    "status": "active",
    "unread_count": 0,
    "created_at": "2026-07-03T10:15:00+00:00",
    "eligible": false,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": []
  }
}
GET /v1/numbers/{id}/private-email/inbox

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
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • page integer query Opcional

    Número de página. Por defecto 1.

  • per_page integer query Opcional

    1-100. Por defecto 25.

Campos de la respuesta
  • data[]array

    id, from_email, from_name, subject, preview, attachment_count, is_read, received_at.

  • metaobject

    current_page, per_page, total, last_page.

  • unread_countinteger

    Nivel superior, junto a data.

Errores
  • 404No es tu número o todavía no tiene dirección.
  • 404private_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"
Respuesta
{
  "success": true,
  "data": [
    {
      "id": 77,
      "from_email": "[email protected]",
      "from_name": "Example Billing",
      "subject": "Your receipt",
      "preview": "Thanks for your order…",
      "attachment_count": 1,
      "is_read": false,
      "received_at": "2026-07-04T08:01:12+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
  "unread_count": 1
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/body

Leer un correo

El correo completo (HTML y texto) con su lista de adjuntos. Al leerlo se marca como leído.

Parámetros
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • messageId integer path Obligatorio

    Id del correo de la lista de la bandeja de entrada.

Errores
  • 404No es tu número o todavía no tiene dirección.
  • 404private_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"
Respuesta
{
  "success": true,
  "data": {
    "id": 77,
    "subject": "Your receipt",
    "from_email": "[email protected]",
    "from_name": "Example Billing",
    "received_at": "2026-07-04T08:01:12+00:00",
    "html": "<p>Thanks for your order…</p>",
    "text": "Thanks for your order…",
    "attachments": [
      { "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
    ]
  }
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}

Descargar un adjunto

El archivo sin procesar, con su propio Content-Type y nombre de archivo. index procede del attachments[] del correo.

Parámetros
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • messageId integer path Obligatorio

    Id del correo de la lista de la bandeja de entrada.

  • index integer path Obligatorio

    attachments[].index de Leer un correo.

Errores
  • 404No es tu número o todavía no tiene dirección.
  • 404private_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
Respuesta
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf

<binary file>
DELETE /v1/numbers/{id}/private-email/inbox/{messageId}

Eliminar un correo

Elimina el correo y sus adjuntos.

Parámetros
  • id integer path Obligatorio

    Id del número de GET /numbers.

  • messageId integer path Obligatorio

    Id del correo de la lista de la bandeja de entrada.

Errores
  • 404No es tu número o todavía no tiene dirección.
  • 404private_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"
Respuesta
{
  "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.

Endpoint
Endpoint MCP · HTTP transmitible
https://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

HerramientaQué haceRequiere "Permitir compras"
get-balanceObtiene el saldo del monedero y la moneda de facturación de la cuenta autenticada.No
get-pricingDevuelve el catálogo de precios activo para todos los países o para un solo código de país ISO.No
get-inventoryConsulta la disponibilidad de inventario en tiempo real para un país, una duración y un tipo de número opcional.No
purchase-numberCompra un número privado para la cuenta autenticada con fondos del monedero.Sí
list-active-numbersDevuelve los números de la cuenta autenticada, con filtro opcional por estado.No
check-smsObtiene los mensajes SMS de un ID de número comprado que pertenezca a la cuenta autenticada.No
renew-numberRenueva un número comprado por ID con un paquete de duración opcional.Sí
cancel-numberCancela 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.

  1. Haz clic en Añadir a Claude. Claude se abrirá con Temp Number y su URL ya rellenados. Haz clic en Add.
  2. Haz clic en Connect, inicia sesión en Temp Number, elige si Claude puede hacer compras y haz clic en Allow.
  3. En cualquier chat, abre el menú + → Connectors y activa Temp Number. Prueba: "¿Cuánto cuesta un número de EE. UU. durante un mes?"
Team y Enterprise: un propietario añade el conector una sola vez en Configuración de la organización → Conectores. Después, cada miembro inicia sesión con su propia cuenta de Temp Number, así que cada uno paga desde su propio monedero.

¿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.

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.

llms.txt Especificación OpenAPI
prompt.md
You are integrating the Temp Number REST API. Read the full, machine-readable reference before writing any code:

- API reference (llms.txt): https://temp-number.com/developers/llms.txt
- OpenAPI spec: https://api.temp-number.com/api.json
- Base URL: https://api.temp-number.com/v1
- MCP server (for AI agents that call tools directly): https://mcp.temp-number.com/mcp - sign in with OAuth, or send an MCP key as a Bearer token.

Rules: authenticate every request with `Authorization: Bearer <YOUR_API_KEY>` (created in the dashboard → API Access) and keep the key in an environment variable, never in code; send and accept JSON over HTTPS; send a unique `Idempotency-Key` (UUID) header on every POST that buys, renews or cancels - it is required, and retries must reuse the same key; branch on the `code` field of error responses, not on the message text; on HTTP 429 or 503, wait for the `Retry-After` header. All prices are final USD.

Task: <describe what you want to build - e.g. "buy a US number, wait for the verification SMS, then cancel it if it never arrives">.
https://temp-number.com/developers/llms.txt 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.

Inicia sesión para empezar