Plataforma para programadores

API Temp Number - Números de telefone, SMS e OTP

Disponibilize números de telefone virtuais, receba SMS em tempo real e automatize a verificação OTP - a partir de uma API REST simples ou diretamente do seu assistente de IA.

REST · JSON MCP para agentes de IA cURL · Node.js · Python · PHP
URL BASE https://api.temp-number.com/v1

Início / Programadores

Introdução

A API Temp Number está organizada em torno de recursos previsíveis, usa verbos HTTP padrão e devolve JSON em todas as respostas. Uma chave dá acesso de leitura e escrita apenas à sua conta - não existe acesso entre contas.

ProtocoloHTTPS · JSON
AutenticaçãoChave Bearer
Versãov1 (estável)
Endpoints17 ativos

Início rápido

Do zero a um código de verificação. Escolha a sua linguagem uma vez - todos os exemplos da página seguem-na.

  1. Criar uma chave de API

    Em Painel → Acesso à API, crie uma chave. É mostrada uma única vez: guarde-a como a variável de ambiente TEMP_NUMBER_API_KEY.

  2. Consultar o saldo

    Todas as chamadas levam a sua chave no cabeçalho Authorization. Comece por algo inofensivo: o saldo da sua carteira.

    curl --request GET "https://api.temp-number.com/v1/account" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  3. Escolha um país e verifique o stock

    GET /pricing lista todos os países com o preço exato por duração. Depois, confirme o stock do que pretende.

    curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  4. Comprar um número

    Envie uma Idempotency-Key nova em cada compra. Se a ligação falhar, tente novamente com a mesma chave: nunca será cobrado duas vezes. Guarde o data.id da resposta.

    curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json" \
      --header "Idempotency-Key: $(uuidgen)" \
      --data '{"country_code":"US","duration":"oneMonth"}'
  5. Ler o SMS

    Consulte o número a cada poucos segundos até a mensagem chegar. Recebe o texto em bruto; extraia o código do seu lado.

    curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  6. Sem SMS? Cancele e receba o reembolso

    Entre 15 e 120 minutos após a compra, um número que não tenha recebido SMS pode ser cancelado com reembolso total para a sua carteira.

    curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Idempotency-Key: $(uuidgen)"

Autenticação

Envie a sua chave de API no cabeçalho padrão Authorization em cada pedido:

http
Authorization: Bearer YOUR_API_KEY
  • Crie chaves em Acesso à API. Cada chave é mostrada por completo uma única vez, no momento da criação.
  • Use uma chave por integração, para poder revogar uma sem afetar as outras. Alterar a palavra-passe revoga todas as chaves.
  • Uma chave em falta, mal formada ou revogada responde com 401. Uma conta que não verificou o email, ou que está suspensa, responde com 403 e o code email_unverified ou account_suspended.
  • As chaves REST funcionam apenas em /v1. O servidor MCP usa o seu próprio início de sessão ou chaves MCP - consulte Servidor MCP.
Trate a sua chave como uma palavra-passe. Mantenha-a no seu servidor, nunca numa página web ou numa aplicação móvel. Substitua-a de imediato se alguma vez tiver sido registada em logs, incluída num commit ou partilhada.

URL base e versões

Todos os endpoints estão sob o prefixo permanente /v1:

URL base
https://api.temp-number.com/v1

As alterações aditivas - novos campos, endpoints ou parâmetros opcionais - são lançadas sem mudança de versão, por isso ignore os campos que não conhece. Uma alteração incompatível seria lançada em /v2; a sua integração nunca é migrada sem aviso. O contrato legível por máquina é a especificação OpenAPI.

Pedidos e respostas

  • Envie corpos JSON com Content-Type: application/json e Accept: application/json em cada pedido.
  • Sucesso: { "success": true, "data": …, "meta": {…} }. meta inclui contagens, paginação e resumos monetários.
  • Erros: { "success": false, "message": "…", "code": "…" }. Use code na lógica; a mensagem destina-se a pessoas. Consulte Erros.
  • As horas estão em ISO 8601. Os valores estão em USD com duas casas decimais - sempre o preço que paga.
  • Alguns objetos ainda mantêm nomes de campos antigos para integrações existentes (marcados como obsoletos na referência). O código novo deve ignorá-los.
As respostas nunca indicam um fornecedor a montante nem mostram o custo grossista. O único preço que vê é o que é cobrado na sua carteira - pode mostrá-lo com segurança aos seus próprios utilizadores.

Erros

Os erros usam códigos de estado HTTP padrão. Os erros de negócio incluem um code estável e legível por máquina; alguns incluem details com mais contexto.

422 · erro de negócio
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · erro de validação
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
EstadocodeSignificadoO que fazer
400 - O cabeçalho Idempotency-Key está em falta ou mal formado na compra, renovação ou cancelamento. Corpo: {"error": "Missing Idempotency-Key header."} Envie um UUID em Idempotency-Key.
401 - Sem token bearer, token mal formado ou chave revogada. Verifique o cabeçalho Authorization; crie uma nova chave se tiver sido revogada.
403 email_unverified A conta ainda não confirmou o endereço de e-mail. Confirme o e-mail no site e tente novamente.
403 account_suspended A conta está suspensa. Contacte o apoio ao cliente.
403 kyc_required A conta tem de verificar a identidade antes de comprar novos números. Nada foi cobrado; as renovações continuam a funcionar. Conclua a verificação de identidade nas definições da conta e tente novamente.
403 - A chave não tem acesso à API (uma chave MCP, por exemplo), ou GET /receive-sms foi pedido para um número de outra conta. Utilize uma chave da API REST; consulte apenas os seus próprios números.
404 - O número, a mensagem ou o país não pertence à sua conta ou não está à venda neste momento. Os ids de outras contas também respondem 404. Volte a listar com GET /numbers ou GET /pricing.
404 private_email_closed A caixa de entrada privada está encerrada porque o respetivo número foi cancelado ou reembolsado. Nada para repetir.
409 - A Idempotency-Key já foi utilizada com um corpo diferente, ou o primeiro pedido com ela ainda está em curso. Utilize uma nova chave para um novo pedido; aguarde e tente novamente para o que está em curso.
422 insufficient_funds A carteira não tem saldo suficiente para o preço. Carregue a carteira e tente novamente.
422 out_of_stock O mercado esgotou entre a sua consulta de preço e a compra. Volte a consultar GET /inventory e escolha outra duração ou tipo.
422 invalid_duration A duração não está disponível para esse país e tipo de número. Volte a obter GET /pricing/{countryCode}.
422 - A validação falhou (um objeto `errors` indica cada campo) ou uma regra recusou a ação, como cancelar fora do prazo de reembolso. Leia `message`; corrija o pedido em vez de o repetir.
429 - Limite de pedidos atingido. Aguarde o tempo indicado no cabeçalho Retry-After e tente novamente com backoff.
503 purchases_paused As novas compras estão suspensas em toda a plataforma. Nada foi cobrado; as renovações e os cancelamentos continuam a funcionar. Tente novamente após Retry-After (60 s).
5xx - Algo falhou do nosso lado. Tente novamente com a MESMA Idempotency-Key - nunca será cobrado duas vezes.

Limites de pedidos

Os limites aplicam-se por chave e, além disso, as chamadas que movimentam dinheiro têm um limite mais restrito por conta:

Aplica-se aLimiteContabilizado
Todos os endpoints60 / minutopor chave de API
Comprar, renovar, cancelar10 / minutopor conta, além dos limites acima
GET /receive-sms60 / minutopor chave de API
GET /receive-sms30 / minutopor chave de API e número de telefone
GET /receive-sms30 / minutopor endereço IP

Acima de um limite recebe 429 com um cabeçalho Retry-After (segundos). Aguarde pelo menos esse tempo e depois recue com jitter. As respostas também incluem X-RateLimit-Limit e X-RateLimit-Remaining.

À espera de um SMS? Consulte cada número no máximo a cada 5 segundos.

Idempotência

POST /numbers/buy, /renew e /cancel exigem um cabeçalho Idempotency-Key: um UUID que cria para cada nova ação. Se a rede falhar, envie o mesmo pedido com a mesma chave - recebe a resposta original (marcada com X-Idempotency-Replayed: true) e nunca é cobrado duas vezes.

  • Chave em falta: 400. As chaves têm até 128 caracteres de letras, dígitos e - _ . :
  • Mesma chave com um corpo diferente: 409. Mesma chave enquanto o primeiro pedido ainda está em curso: 409 - aguarde um momento e tente novamente.
  • As chaves são memorizadas por conta e por endpoint. Nunca reutilize uma chave para uma compra diferente.

Paginação

GET /receive-sms usa paginação por cursor, dos mais recentes para os mais antigos. Leia meta.hasMore; enquanto for true, envie meta.nextCursor de volta como cursor com o mesmo phoneNumber. Os cursores são opacos - não os construa nem os edite.

página seguinte
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9

As listas que são pequenas por natureza (/numbers, /pricing) devolvem tudo numa única resposta; a caixa de entrada privada usa page e per_page.

Utilização aceitável

A API foi criada para programadores: fluxos de verificação e OTP, onboarding automatizado, QA e testes de sistemas, e qualquer produto que precise de SMS recebidos ou de números de telefone em grande escala.

  • Utilize-a apenas para verificação legítima, desenvolvimento e testes.
  • Sem burlas, spam, fraude ou engano. Os números usados para burlas ou outras atividades abusivas levam ao banimento imediato e sem aviso da conta, ao cancelamento dos números associados e não dão direito a reembolso.
  • Não se destina a contas reguladas ou associadas à identidade. Os nossos números temporários e partilhados não suportam a verificação por SMS para serviços bancários, de pagamento, de criptomoedas, governamentais ou outros que verifiquem a sua identidade legal (KYC/AML) - para esses, use o seu próprio número de telemóvel pessoal.
Monitorizamos utilizações abusivas. As condições completas estão nos nossos Termos de Serviço.

Referência da API

Todos os endpoints /v1 ativos. Os pedidos estão à direita na sua linguagem; as respostas têm a estrutura real.

Conta

Consulte o saldo da sua carteira e a moeda de liquidação.

GET /v1/account

Obter o saldo da conta

Devolve o saldo disponível na carteira e a respetiva moeda. Consulte-o antes de uma compra para poder parar a tempo com uma mensagem clara de "carregue a carteira".

Campos da resposta
  • balancenumber

    Saldo disponível na carteira.

  • currencystring

    Moeda de liquidação, USD.

Erros
  • 401Chave em falta ou inválida.
curl --request GET "https://api.temp-number.com/v1/account" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "success": true,
  "balance": 124.50,
  "currency": "USD"
}

Preços e stock

Explore os mercados disponíveis, o preço exato que paga por duração e o stock em tempo real.

O objeto de preços por país

Um país e todos os pacotes que pode comprar nele. price é o montante final cobrado à sua carteira; o custo a montante nunca é revelado.

Campos
  • country_codestring

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

  • country_namestring

    Nome apresentado.

  • packages[].number_typeenum

    voip ou non_voip.

  • packages[].durationenum

    A chave que envia para comprar: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths ou oneYear. Cada país oferece o seu próprio conjunto.

  • packages[].duration_labelstring

    Etiqueta legível, p. ex. "1 Mês".

  • packages[].pricenumber

    Preço final em USD.

  • packages[].original_pricenumber | null

    O preço antes do desconto, quando se aplica.

  • 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 preços de todos os países

O catálogo completo em tempo real: uma lista de objetos de preços por país. O campo price é a tarifa final apresentada ao utilizador em USD, exatamente o que é cobrado à sua carteira.

Devolve

Uma lista de objetos de preços por país em data, com meta.count.

Erros
  • 401Chave em falta ou inválida.
curl --request GET "https://api.temp-number.com/v1/pricing" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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}

Obter preços de um país

Preços em tempo real de um único país. Um 404 significa que o país não tem nenhuma rota ativa neste momento: trate-o como "esgotado" temporário e não como "nunca vendido".

Parâmetros
  • countryCode string path Obrigatório

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

Devolve

Um objeto de preços por país em data.

Erros
  • 404Nenhuma rota ativa para esse país neste momento.
curl --request GET "https://api.temp-number.com/v1/pricing/GB" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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

Verificar stock

Stock em tempo real para um país e uma duração, para poder desativar um botão de compra antes de alguém clicar nele. Omita number_type para obter todos os tipos lado a lado em types[]. Um resultado verde é um forte indicador, mas a própria compra é a verificação final.

Parâmetros
  • country_code string query Obrigatório

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

  • duration enum query Opcional

    Uma chave de duração de GET /pricing/{countryCode}. Omita para usar a predefinição da rota.

    Um de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query Opcional

    Limite a verificação a um tipo. Omita para ver todos os tipos.

    Um de voipnon_voip
Campos da resposta
  • stockinteger | null

    Números disponíveis (somados em types[] quando number_type é omitido).

  • availableboolean

    True quando é possível comprar, pelo menos, um número.

  • statusstring

    Etiqueta legível: Em stock, Esgotado, Brevemente…

  • types[]array

    Apenas quando number_type é omitido: number_type, stock, available, status para cada tipo que o mercado vende.

Erros
  • 422Nada à venda para essa seleção; details contém os campos de stock.
curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "success": true,
  "data": {
    "country_code": "US",
    "duration": "oneMonth",
    "number_type": null,
    "stock": 47,
    "available": true,
    "status": "In Stock",
    "types": [
      { "number_type": "voip", "stock": 0, "available": false, "status": "Out of Stock" },
      { "number_type": "non_voip", "stock": 47, "available": true, "status": "In Stock" }
    ]
  }
}

Números

Liste, compre, renove e cancele os seus números privados. As chamadas que movimentam dinheiro são idempotentes e seguras contra repetições.

O objeto de número

Um número da sua conta. Comprar, renovar e cancelar também devolvem um resumo financeiro em meta: charged (ou refunded), currency e wallet_balance_after.

Campos
  • idinteger

    Utilize-o nas chamadas /numbers/{id}/…. Os webhooks enviam-no como number.rentalId.

  • phone_numberstring

    E.164, p. ex. +14035551234.

  • country_codestring | null

    ISO 3166-1 alfa-2.

  • country_namestring

    Nome apresentado.

  • number_typeenum

    voip ou non_voip.

  • statusenum

    active, expired, cancelled ou refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 8601, UTC. A partir daí, o número deixa de receber SMS e não pode ser renovado.

Aliases obsoletos ainda enviados para integrações antigas: country, provider, purchased_at e expires_at (milissegundos epoch). Não dependa deles.

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 os seus números

Todos os números da sua conta, dos mais recentes para os mais antigos. Utilize status=expiring_soon (números ativos a menos de 10 dias de expirar) para gerir lembretes de renovação.

Parâmetros
  • status enum query Opcional

    Filtro de ciclo de vida. Predefinição: all.

    Um de allactiveexpiring_soonexpiredcancelled
Devolve

Uma lista de objetos de número em data; meta.count e meta.status.

Erros
  • 401Chave em falta ou inválida.
curl --request GET "https://api.temp-number.com/v1/numbers?status=expiring_soon" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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 obrigatório

Comprar um número

Atribui um novo número privado e cobra à sua carteira num único passo atómico. Se a entrega falhar após a cobrança, esta é revertida: nunca fica a pagar sem receber nada. A resposta mostra o montante cobrado e o saldo resultante.

Parâmetros
  • country_code string body Obrigatório

    Um país de GET /pricing.

  • duration enum body Obrigatório

    Uma chave de duração do packages[] desse país - cada país oferece o seu próprio conjunto.

    Um de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body Opcional

    Omita para usar a predefinição da rota.

    Um de voipnon_voip
  • Idempotency-Key string header Obrigatório

    Um UUID, novo em cada compra e reutilizado nas novas tentativas.

Devolve

O novo objeto de número em data; meta.charged, meta.currency, meta.wallet_balance_after.

Erros
  • 422insufficient_fundsA carteira não tem saldo suficiente para o preço.
  • 422out_of_stockEsgotado desde a sua verificação de stock.
  • 422invalid_durationDuração não disponível para este país/tipo.
  • 403kyc_requiredÉ necessária primeiro a verificação de identidade. Nada foi cobrado.
  • 503purchases_pausedCompras suspensas em toda a plataforma. Retry-After: 60.
curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"country_code":"US","duration":"oneMonth","number_type":"voip"}'
Resposta
{
  "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 obrigatório

Renovar um número

Prolonga um número com o pacote escolhido. O novo período é somado à validade atual, por isso renovar antecipadamente não faz perder nada. O preço é a tarifa atual do site, calculada por nós. Os números expirados não podem ser renovados: compre um novo.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • package enum body Opcional

    Duração da renovação. Predefinição: oneMonth. (duration é aceite como alias antigo.)

    Um de oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header Obrigatório

    Um UUID, novo em cada renovação e reutilizado nas novas tentativas.

Devolve

O objeto de número atualizado em data; meta.charged, meta.currency, meta.wallet_balance_after.

Erros
  • 404Não é um número da sua conta.
  • 422insufficient_fundsA carteira não tem saldo suficiente para a renovação.
  • 422Expirado, cancelado ou não renovável.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/renew" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"package":"threeMonths"}'
Resposta
{
  "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 obrigatório

Cancelar um número para obter reembolso

Liberta um número e reembolsa o preço total para a sua carteira. Só é permitido entre 15 e 120 minutos após a compra, enquanto o número estiver ativo e antes de ter recebido qualquer SMS. Fora destas regras, a chamada é recusada com 422 e nada muda; se for demasiado cedo, details.seconds_until_open indica quanto tempo deve esperar.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • Idempotency-Key string header Obrigatório

    Um UUID, reutilizado nas novas tentativas.

Devolve

O objeto de número (status cancelled) em data; meta.refunded, meta.currency, meta.wallet_balance_after.

Erros
  • 404Não é um número da sua conta.
  • 422Demasiado cedo (menos de 15 min), demasiado tarde (mais de 120 min), já recebeu SMS ou não está ativo.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)"
Resposta
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "cancelled",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "refunded": 4.99,
    "currency": "USD",
    "wallet_balance_after": 124.50
  }
}

SMS

Leia os SMS que os seus números recebem. Recebe o texto em bruto; a extração do código fica a seu cargo.

O objeto de mensagem SMS

Um SMS recebido, tal como devolvido por GET /numbers/{id}/sms. (GET /receive-sms utiliza uma variante em camelCase, apresentada nesse endpoint.)

Campos
  • idinteger

    Id da mensagem.

  • fromstring

    Remetente: um número de telefone ou um nome, como WhatsApp.

  • bodystring

    O texto completo da mensagem.

  • received_atstring

    ISO 8601, UTC.

Aliases obsoletos ainda enviados: sender (= from) e message (= body).

objeto
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /v1/numbers/{id}/sms

Obter um número e os respetivos SMS

Um número com todos os SMS que recebeu, dos mais recentes para os mais antigos. Ideal para uma vista de "detalhe deste número" e para consultar periodicamente um único número enquanto espera por um código. Ids que não são seus respondem 404.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

Devolve

data.number (um objeto de número) e data.messages (objetos de mensagem SMS); meta.count.

Erros
  • 404Não é um número da sua conta.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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

Receber SMS por número de telefone

SMS paginados por cursor de um número seu, identificado pelo número de telefone em vez do id. Ideal para caixas de entrada com muito volume. Um número que não seja seu responde 403.

Parâmetros
  • phoneNumber string query Obrigatório

    E.164 ou apenas algarismos, p. ex. +14035551234. Codifique o + no URL.

  • limit integer query Opcional

    Tamanho da página 1-100. Predefinição: 50.

  • cursor string query Opcional

    meta.nextCursor da página anterior.

Campos da resposta
  • data.messages[].idinteger

    Id da mensagem.

  • data.messages[].fromstring

    Remetente.

  • data.messages[].tostring

    O seu número.

  • data.messages[].messagestring

    O texto completo.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    Passe nextCursor como cursor para a página seguinte.

Erros
  • 403O número não pertence à sua conta.
  • 422phoneNumber em falta ou inválido.
curl --request GET "https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "success": true,
  "data": {
    "phoneNumber": "+14035551234",
    "purchaseStatus": "active",
    "messages": [
      {
        "id": 1842,
        "from": "WhatsApp",
        "to": "+14035551234",
        "message": "Your verification code is 483920.",
        "receivedAt": "2026-05-13T17:43:14+00:00"
      }
    ]
  },
  "meta": {
    "count": 1,
    "pageSize": 50,
    "hasMore": false,
    "nextCursor": null,
    "prevCursor": null,
    "requestedAt": "2026-05-13T17:43:20+00:00"
  }
}

Email privado

Uma caixa de entrada [email protected] gratuita, só de receção, para cada número privado. Um endereço por número.

O objeto de e-mail privado

A caixa de entrada associada a um número.

Campos
  • addressstring | null

    O endereço, ou null antes de ser obtido.

  • statusenum

    active ou none.

  • unread_countinteger

    E-mails não lidos.

  • created_atstring | null

    Quando o endereço foi obtido.

  • eligibleboolean

    True quando o número pode obter um endereço agora.

  • linked_numberstring

    O número de telefone a que pertence.

  • domainstring

    privnum.com

  • suggestionsstring[]

    Sugestões de nomes enquanto for elegível.

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

Obter o e-mail privado

O endereço de um número ou, antes de ser obtido, se pode ter um e algumas sugestões de nomes.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

Devolve

Um objeto de e-mail privado em data.

Erros
  • 404Não é um número da sua conta.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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

Verificar um nome

Verificação em tempo real de que um nome é válido e está livre antes de o obter.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • local_part string query Obrigatório

    A parte antes de @: 3-64 letras, algarismos, pontos, hífenes ou sublinhados.

Campos da resposta
  • availableboolean

    True quando o pode obter.

  • reasonenum | null

    too_short, too_long, invalid, reserved ou taken.

Erros
  • 404Não é um número da sua conta.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /v1/numbers/{id}/private-email

Obter um endereço

Atribui um endereço a um número ativo. Gratuito, um por número, e um endereço obtido nunca é entregue a mais ninguém.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • local_part string body Obrigatório

    O nome que verificou.

Devolve

O objeto de e-mail privado em data.

Erros
  • 404Não é o seu número ou ainda não tem endereço.
  • 422Nome ocupado ou inválido (details.reason), o número já tem um endereço ou não está ativo.
curl --request POST "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"local_part":"alex.smith"}'
Resposta
{
  "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 e-mails

Resumos dos e-mails, dos mais recentes para os mais antigos, com paginação por páginas e a contagem de não lidos no nível superior.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • page integer query Opcional

    Número da página. Predefinição: 1.

  • per_page integer query Opcional

    1-100. Predefinição: 25.

Campos da resposta
  • 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

    No nível superior, junto a data.

Erros
  • 404Não é o seu número ou ainda não tem endereço.
  • 404private_email_closedO número foi cancelado ou reembolsado.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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

Ler um e-mail

O e-mail completo (HTML e texto) com a lista de anexos. Lê-lo marca-o como lido.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • messageId integer path Obrigatório

    Id do e-mail da lista da caixa de entrada.

Erros
  • 404Não é o seu número ou ainda não tem endereço.
  • 404private_email_closedO número foi cancelado ou reembolsado.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "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}

Transferir um anexo

O ficheiro em bruto, com o seu próprio Content-Type e nome de ficheiro. index vem do attachments[] do e-mail.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • messageId integer path Obrigatório

    Id do e-mail da lista da caixa de entrada.

  • index integer path Obrigatório

    attachments[].index de Ler um email.

Erros
  • 404Não é o seu número ou ainda não tem endereço.
  • 404private_email_closedO número foi cancelado ou reembolsado.
  • 404Não existe nenhum anexo nesse índice.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --output receipt.pdf
Resposta
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 um e-mail

Elimina o e-mail e os respetivos anexos.

Parâmetros
  • id integer path Obrigatório

    Id do número de GET /numbers.

  • messageId integer path Obrigatório

    Id do e-mail da lista da caixa de entrada.

Erros
  • 404Não é o seu número ou ainda não tem endereço.
  • 404private_email_closedO número foi cancelado ou reembolsado.
curl --request DELETE "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Resposta
{
  "success": true,
  "data": null
}

IA e MCP

Deixe um assistente de IA usar diretamente a sua conta, ou dê a um agente de programação tudo o que precisa para desenvolver sobre a API.

Servidor MCP

Para além da API REST, disponibilizamos um servidor Model Context Protocol. Ligue-o ao Claude, ao ChatGPT ou ao seu editor e o assistente pode consultar preços e stock, comprar um número e ler os respetivos SMS como ferramentas nativas, sem código da sua parte. Novo no MCP? Comece pela visão geral do servidor MCP.

Endpoint
Endpoint MCP · HTTP streamable
https://mcp.temp-number.com/mcp

Como funciona o início de sessão

  • Adicione o URL à sua app de IA. Ela redireciona-o para a Temp Number para iniciar sessão com a sua própria conta (OAuth 2.1 com PKCE) - sem chave para copiar.
  • No ecrã de consentimento, escolhe o que o assistente pode fazer. Ler o saldo, os preços, os seus números e os respetivos SMS está sempre incluído. Permitir compras - comprar, renovar e cancelar com a sua carteira - fica desativado, a menos que o assinale.
  • Todas as ligações estão listadas em Painel → Servidor MCP → Apps ligadas, onde pode desligá-las a qualquer momento.
  • Prefere uma chave (CI, scripts, agentes headless)? Crie uma chave MCP na mesma página e envie-a como Authorization: Bearer <key>. As chaves MCP e as chaves da API REST não são intercambiáveis.

Ferramentas

FerramentaO que fazRequer "Permitir compras"
get-balanceObtém o saldo da carteira da conta autenticada e a moeda de faturação.Não
get-pricingDevolve o catálogo de preços ativo para todos os países ou para um único código de país ISO.Não
get-inventoryConsulta a disponibilidade de inventário em tempo real para um país, uma duração e um tipo de número opcional.Não
purchase-numberCompra um número privado para a conta autenticada com fundos da carteira.Sim
list-active-numbersDevolve os números da conta autenticada, com filtro opcional por estado.Não
check-smsObtém as mensagens SMS de um ID de número comprado que pertence à conta autenticada.Não
renew-numberRenova um número comprado pelo ID com um pacote de duração opcional.Sim
cancel-numberCancela um número comprado pelo ID e devolve à carteira o reembolso elegível.Sim

Ligue a sua ferramenta de IA

Escolha a sua app. A maioria liga-se num clique: inicia sessão na Temp Number, assinala o que o assistente pode fazer e clica em Permitir.

Claude - claude.ai, desktop e telemóvel

Nada para instalar. Funciona no navegador, na app de desktop e no telemóvel.

  1. Clique em Adicionar ao Claude. O Claude abre com a Temp Number e o respetivo URL já preenchidos. Clique em Add.
  2. Clique em Connect, inicie sessão na Temp Number, escolha se o Claude pode fazer compras e clique em Permitir.
  3. Em qualquer chat, abra o menu + → Connectors e ative a Temp Number. Experimente: "Quanto custa um número dos EUA por um mês?"
Team e Enterprise: um proprietário adiciona o conector uma vez em Definições da organização → Conectores. Depois, cada membro inicia sessão com a sua própria conta Temp Number, para que cada um gaste da sua própria carteira.

Não vê o botão? No Claude, vá a Customize → Connectors → Add custom connector e cole o endpoint MCP. As organizações com a opção de cabeçalho de pedido do Claude podem enviar uma chave MCP como Authorization: Bearer <key> em vez de iniciar sessão.

llms.txt e prompt do agente

Está a desenvolver com um assistente de programação com IA? Dê-lhe o contexto abaixo e ele consegue integrar a API corretamente à primeira - autenticação, idempotência e limites de pedidos incluídos.

llms.txt Especificação 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 é um resumo em texto simples, sempre atualizado, de todos os endpoints; a especificação OpenAPI é o contrato tipado. Ambos são atualizados com a API.

Recursos

O que mudou e onde obter ajuda.

Registo de alterações

Apenas alterações aditivas - nada foi removido de /v1.

  • NewMCP: inicie sessão com a sua conta Temp Number

    "Add to Claude" com um clique, além de ChatGPT, Claude Code, Codex, Cursor e VS Code sem copiar nenhuma chave. Escolhe no ecrã de consentimento se a IA pode gastar.

  • DocsUma nova casa para a documentação

    Início rápido, pesquisa e todos os exemplos em cURL, Node.js, Python e PHP. Os erros, limites de pedidos e reembolsos correspondem agora exatamente à API em produção.

  • Newllms.txt para todo o site

    Um mapa do serviço em texto simples para assistentes de IA, com ligação para a referência da API preparada para agentes.

  • NewLigue a sua ferramenta de IA

    Configuração para Claude Code, Codex, Cursor e VS Code, com ligações de instalação com um clique para Cursor e VS Code.

  • NewEspecificação OpenAPI

    O contrato legível por máquina está disponível em https://api.temp-number.com/api.json.

  • ImprovedOs objetos correspondem à referência

    Os números e SMS utilizam datas ISO 8601 e from/body. Os erros incluem um código legível por máquina (out_of_stock, insufficient_funds, invalid_duration). /inventory indica todos os tipos de número quando omite number_type. Os nomes de campos antigos continuam a funcionar como aliases obsoletos.

  • NewEndpoints de e-mail privado

    Obtenha uma caixa de entrada [email protected] gratuita para um número, leia e-mails e transfira anexos através da API.

  • NewServidor MCP

    Os agentes de IA podem consultar preços, comprar números e ler SMS como ferramentas, com uma chave MCP.

  • LaunchAPI REST pública v1

    Conta, preços, inventário, ciclo de vida dos números e SMS, com autenticação por token Bearer.

Suporte

Está com dificuldades, ou encontrou algo nesta documentação que não corresponde ao que a API faz? Contacte-nos - inclua o endpoint, a hora do pedido e o corpo da resposta (nunca a sua chave de API).

Pronto para começar a desenvolver?

Crie uma chave e faça a sua primeira chamada em menos de um minuto.

Inicie sessão para começar