Plateforme développeurs

API Temp Number - Numéros de téléphone, SMS et OTP

Obtenez des numéros de téléphone virtuels, recevez des SMS en temps réel et automatisez la vérification OTP - via une API REST claire, ou directement depuis votre assistant IA.

REST · JSON MCP pour les agents IA cURL · Node.js · Python · PHP
URL DE BASE https://api.temp-number.com/v1
Documentation API v1 Obtenir une clé API

Accueil / Développeurs

Introduction

L'API Temp Number est organisée autour de ressources prévisibles, utilise les verbes HTTP standard et renvoie du JSON pour chaque réponse. Une clé donne un accès en lecture et en écriture à votre compte uniquement - aucun accès à d'autres comptes n'est possible.

ProtocoleHTTPS · JSON
AuthClé Bearer
Versionv1 (stable)
Endpoints17 en ligne

Démarrage rapide

De zéro à un code de vérification. Choisissez votre langage une fois - tous les exemples de la page suivront.

  1. Créer une clé API

    Dans Tableau de bord → Accès API, créez une clé. Elle n'est affichée qu'une fois : enregistrez-la dans la variable d'environnement TEMP_NUMBER_API_KEY.

  2. Consulter votre solde

    Chaque appel transmet votre clé dans l'en-tête Authorization. Commencez par quelque chose d'inoffensif : le solde de votre portefeuille.

    curl --request GET "https://api.temp-number.com/v1/account" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  3. Choisir un pays et vérifier le stock

    GET /pricing liste chaque pays avec le prix exact pour chaque durée. Vérifiez ensuite le stock pour celui qui vous intéresse.

    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. Acheter un numéro

    Envoyez une nouvelle Idempotency-Key à chaque achat. Si le réseau coupe, réessayez avec la même clé : vous n'êtes jamais débité deux fois. Conservez data.id de la réponse.

    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. Lire les SMS

    Interrogez le numéro toutes les quelques secondes jusqu'à l'arrivée du message. Vous recevez le texte brut ; à vous d'en extraire le code.

    curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  6. Pas de SMS ? Annulez pour être remboursé

    Entre 15 et 120 minutes après l'achat, un numéro qui n'a reçu aucun SMS peut être annulé contre un remboursement intégral sur votre portefeuille.

    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)"

Authentification

Envoyez votre clé API dans l'en-tête standard Authorization avec chaque requête :

http
Authorization: Bearer YOUR_API_KEY
  • Créez des clés dans Accès API. Une clé n'est affichée en entier qu'une seule fois, lors de sa création.
  • Utilisez une clé par intégration, pour pouvoir en révoquer une sans casser les autres. Changer votre mot de passe révoque toutes les clés.
  • Une clé absente, mal formée ou révoquée renvoie 401. Un compte dont l'e-mail n'a pas été vérifié, ou qui est suspendu, renvoie 403 avec le code email_unverified ou account_suspended.
  • Les clés REST fonctionnent uniquement sur /v1. Le serveur MCP utilise sa propre connexion ou des clés MCP - voir Serveur MCP.
Traitez votre clé comme un mot de passe. Conservez-la sur votre serveur, jamais dans une page web ou une application mobile. Renouvelez-la immédiatement si elle a été journalisée, commitée ou partagée.

URL de base et versions

Tous les endpoints se trouvent sous le préfixe permanent /v1 :

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

Les changements additifs - nouveaux champs, endpoints ou paramètres facultatifs - sont publiés sans changement de version : ignorez donc les champs que vous ne connaissez pas. Un changement incompatible serait publié sous /v2 ; votre intégration n'est jamais migrée à votre insu. Le contrat lisible par machine est la spécification OpenAPI.

Requêtes et réponses

  • Envoyez les corps JSON avec Content-Type: application/json, et Accept: application/json avec chaque requête.
  • Succès : { "success": true, "data": …, "meta": {…} }. meta contient les décomptes, la pagination et les récapitulatifs financiers.
  • Erreurs : { "success": false, "message": "…", "code": "…" }. Basez votre logique sur code ; le message est destiné aux humains. Voir Erreurs.
  • Les heures sont au format ISO 8601. Les montants sont en USD avec deux décimales - toujours le prix que vous payez.
  • Certains objets conservent d'anciens noms de champs pour les intégrations existantes (marqués comme obsolètes dans la référence). Le nouveau code doit les ignorer.
Les réponses ne nomment jamais de fournisseur en amont et n'affichent jamais de coût de gros. Le seul prix visible est celui débité de votre portefeuille - vous pouvez l'afficher sans risque à vos propres utilisateurs.

Erreurs

Les erreurs utilisent les codes de statut HTTP standard. Les erreurs métier comportent un code stable et lisible par machine ; certaines comportent des details avec plus de contexte.

422 · erreur métier
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · erreur de validation
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
StatutcodeSignificationQue faire
400 - L'en-tête Idempotency-Key est manquant ou mal formé lors d'un achat, d'un renouvellement ou d'une annulation. Corps : {"error": "Missing Idempotency-Key header."} Envoyez un UUID dans Idempotency-Key.
401 - Aucun jeton Bearer, un jeton mal formé ou une clé révoquée. Vérifiez l'en-tête Authorization ; créez une nouvelle clé si elle a été révoquée.
403 email_unverified Le compte n'a pas encore vérifié son adresse e-mail. Vérifiez l'e-mail sur le site, puis réessayez.
403 account_suspended Le compte est suspendu. Contactez le support.
403 kyc_required Le compte doit vérifier son identité avant d'acheter de nouveaux numéros. Rien n'a été débité ; les renouvellements fonctionnent toujours. Effectuez la vérification d'identité dans les paramètres du compte, puis réessayez.
403 - La clé n'a pas d'accès API (une clé MCP, par exemple), ou GET /receive-sms a été appelé pour un numéro d'un autre compte. Utilisez une clé d'API REST ; interrogez uniquement vos propres numéros.
404 - Le numéro, le message ou le pays n'appartient pas à votre compte ou n'est pas en vente pour le moment. Les ids d'autres comptes renvoient aussi 404. Relancez la liste avec GET /numbers ou GET /pricing.
404 private_email_closed La boîte de réception privée est fermée, car son numéro a été annulé ou remboursé. Rien à réessayer.
409 - L'Idempotency-Key a déjà été utilisée avec un autre corps, ou la première requête qui l'utilise est toujours en cours. Utilisez une nouvelle clé pour une nouvelle requête ; attendez puis réessayez pour celle en cours.
422 insufficient_funds Le solde du portefeuille ne couvre pas le prix. Rechargez le portefeuille et réessayez.
422 out_of_stock Le marché s'est retrouvé en rupture de stock entre votre vérification du prix et l'achat. Revérifiez GET /inventory et choisissez une autre durée ou un autre type.
422 invalid_duration Cette durée n'est pas proposée pour ce pays et ce type de numéro. Récupérez à nouveau GET /pricing/{countryCode}.
422 - La validation a échoué (un objet `errors` indique chaque champ) ou une règle a refusé l'action, par exemple une annulation hors de la période de remboursement. Lisez `message` ; corrigez la requête plutôt que de la réessayer.
429 - Limite de débit atteinte. Attendez l'en-tête Retry-After, puis réessayez avec un délai progressif.
503 purchases_paused Les nouveaux achats sont suspendus sur toute la plateforme. Rien n'a été débité ; les renouvellements et annulations fonctionnent toujours. Réessayez après Retry-After (60 s).
5xx - Une erreur s'est produite de notre côté. Réessayez avec la MÊME Idempotency-Key - vous ne serez jamais débité deux fois.

Limites de débit

Les limites s'appliquent par clé, et les appels qui déplacent de l'argent ont en plus une limite plus stricte par compte :

S'applique àLimiteComptabilisé
Tous les endpoints60 / minutepar clé API
Acheter, renouveler, annuler10 / minutepar compte, en plus des limites ci-dessus
GET /receive-sms60 / minutepar clé API
GET /receive-sms30 / minutepar clé API et numéro de téléphone
GET /receive-sms30 / minutepar adresse IP

Au-delà d'une limite, vous recevez 429 avec un en-tête Retry-After (en secondes). Attendez au moins cette durée, puis espacez vos tentatives avec un délai aléatoire. Les réponses comportent aussi X-RateLimit-Limit et X-RateLimit-Remaining.

Vous attendez un SMS ? Interrogez un même numéro au plus toutes les 5 secondes.

Idempotence

POST /numbers/buy, /renew et /cancel exigent un en-tête Idempotency-Key : un UUID que vous créez pour chaque nouvelle action. Si la connexion réseau est interrompue, renvoyez la même requête avec la même clé - vous recevez la réponse d'origine (marquée X-Idempotency-Replayed: true) et vous n'êtes jamais débité deux fois.

  • Clé manquante : 400. Les clés comptent jusqu'à 128 caractères parmi lettres, chiffres et - _ . :
  • Même clé avec un corps différent : 409. Même clé alors que la première requête est encore en cours : 409 - patientez un instant et réessayez.
  • Les clés sont mémorisées par compte et par endpoint. Ne réutilisez jamais une clé pour un autre achat.

Pagination

GET /receive-sms utilise une pagination par curseur, du plus récent au plus ancien. Lisez meta.hasMore ; tant qu'il vaut true, renvoyez meta.nextCursor comme cursor avec le même phoneNumber. Les curseurs sont opaques - ne les construisez pas et ne les modifiez pas.

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

Les listes naturellement courtes (/numbers, /pricing) renvoient tout en une seule réponse ; la boîte de réception privée utilise page et per_page.

Utilisation acceptable

L'API est conçue pour les développeurs : flux de vérification et d'OTP, inscription automatisée, tests d'assurance qualité et tests système, et tout produit qui a besoin de SMS entrants ou de numéros de téléphone à grande échelle.

  • Utilisez-le uniquement pour la vérification légitime, le développement et les tests.
  • Aucune arnaque, aucun spam, aucune fraude ni tromperie. L'utilisation de numéros pour des arnaques ou toute autre activité abusive entraîne le bannissement immédiat et sans préavis du compte, l'annulation des numéros associés, et aucun remboursement n'est dû.
  • Pas pour les comptes réglementés ou liés à l'identité. Nos numéros temporaires partagés ne prennent pas en charge la vérification par SMS pour les services bancaires, de paiement, de cryptomonnaie, administratifs ou tout autre service qui vérifie votre identité légale (KYC/AML) - utilisez votre propre numéro de mobile personnel pour ceux-ci.
Nous surveillons les abus. L'ensemble des conditions figure dans nos Conditions d'utilisation.

Référence de l'API

Tous les endpoints /v1 en service. Les requêtes figurent à droite dans votre langage ; les réponses ont leur forme réelle.

Compte

Consultez le solde de votre portefeuille et la devise de règlement.

GET /v1/account

Obtenir le solde du compte

Renvoie le solde disponible du portefeuille et sa devise. Vérifiez-le avant un achat pour pouvoir vous arrêter tôt avec un message clair invitant à recharger.

Champs de la réponse
  • balancenumber

    Solde disponible du portefeuille.

  • currencystring

    Devise de règlement, USD.

Erreurs
  • 401Clé manquante ou invalide.
curl --request GET "https://api.temp-number.com/v1/account" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "success": true,
  "balance": 124.50,
  "currency": "USD"
}

Tarifs et stock

Parcourez les marchés disponibles, le prix exact que vous payez pour chaque durée et le stock en temps réel.

L'objet de tarification par pays

Un pays et toutes les formules que vous pouvez y acheter. price est le montant final débité de votre portefeuille ; le coût en amont n'est jamais exposé.

Champs
  • country_codestring

    Code ISO 3166-1 alpha-2, par ex. US.

  • country_namestring

    Nom affiché.

  • packages[].number_typeenum

    voip ou non_voip.

  • packages[].durationenum

    La clé à envoyer pour acheter : halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths ou oneYear. Chaque pays propose ses propres durées.

  • packages[].duration_labelstring

    Libellé lisible, par ex. "1 Month".

  • packages[].pricenumber

    Prix final en USD.

  • packages[].original_pricenumber | null

    Le prix avant remise, lorsqu'une remise s'applique.

  • packages[].updated_atnull

    Réservé.

objet
{
  "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

Lister les tarifs de tous les pays

Le catalogue complet en direct : une liste d'objets de tarification par pays. Le champ price est le tarif final affiché à l'utilisateur en USD, exactement le montant débité de votre portefeuille.

Renvoie

Une liste d'objets de tarification par pays dans data, avec meta.count.

Erreurs
  • 401Clé manquante ou invalide.
curl --request GET "https://api.temp-number.com/v1/pricing" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "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}

Obtenir les tarifs d'un pays

Tarifs en direct pour un seul pays. Une erreur 404 signifie que le pays n'a pas de route active pour le moment : considérez-la comme une rupture de stock temporaire, et non comme « jamais vendu ».

Paramètres
  • countryCode string path Obligatoire

    Code pays ISO 3166-1 alpha-2, par ex. US, GB, CA.

Renvoie

Un objet de tarification par pays dans data.

Erreurs
  • 404Aucune route active pour ce pays pour le moment.
curl --request GET "https://api.temp-number.com/v1/pricing/GB" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "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

Vérifier le stock

Stock en temps réel pour un pays et une durée, pour désactiver un bouton Acheter avant que quiconque ne clique. Omettez number_type pour obtenir tous les types côte à côte dans types[]. Un résultat positif est un bon indicateur, mais c'est l'achat lui-même qui fait foi.

Paramètres
  • country_code string query Obligatoire

    Code pays ISO 3166-1 alpha-2.

  • duration enum query Facultatif

    Une clé de durée issue de GET /pricing/{countryCode}. Omettez-la pour utiliser la valeur par défaut de la route.

    L'un de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query Facultatif

    Limitez la vérification à un type. Omettez-le pour voir tous les types.

    L'un de voipnon_voip
Champs de la réponse
  • stockinteger | null

    Numéros disponibles (additionnés sur types[] lorsque number_type est omis).

  • availableboolean

    Vrai lorsqu'au moins un numéro peut être acheté.

  • statusstring

    Libellé lisible : In Stock, Out of Stock, Coming Soon…

  • types[]array

    Uniquement lorsque number_type est omis : number_type, stock, available, status pour chaque type vendu sur ce marché.

Erreurs
  • 422Rien en vente pour cette sélection ; details contient les champs 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"
Réponse
{
  "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" }
    ]
  }
}

Numéros

Listez, achetez, renouvelez et annulez vos numéros privés. Les appels qui déplacent de l'argent sont idempotents et peuvent être rejoués sans risque.

L'objet numéro

Un numéro de votre compte. L'achat, le renouvellement et l'annulation renvoient aussi un récapitulatif financier dans meta : charged (ou refunded), currency et wallet_balance_after.

Champs
  • idinteger

    Utilisez-le dans les appels /numbers/{id}/…. Les webhooks l'envoient sous number.rentalId.

  • phone_numberstring

    Format E.164, par ex. +14035551234.

  • country_codestring | null

    ISO 3166-1 alpha-2.

  • country_namestring

    Nom affiché.

  • number_typeenum

    voip ou non_voip.

  • statusenum

    active, expired, cancelled ou refunded.

  • purchase_datestring

    ISO 8601, UTC.

  • expire_datestring

    ISO 8601, UTC. Passé ce délai, le numéro ne reçoit plus de SMS et ne peut plus être renouvelé.

Alias obsolètes encore envoyés pour les anciennes intégrations : country, provider, purchased_at et expires_at (millisecondes epoch). Ne vous appuyez pas dessus.

objet
{
  "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

Lister vos numéros

Tous les numéros de votre compte, du plus récent au plus ancien. Utilisez status=expiring_soon (numéros actifs expirant dans moins de 10 jours) pour gérer les rappels de renouvellement.

Paramètres
  • status enum query Facultatif

    Filtre de cycle de vie. Par défaut all.

    L'un de allactiveexpiring_soonexpiredcancelled
Renvoie

Une liste d'objets numéro dans data ; meta.count et meta.status.

Erreurs
  • 401Clé manquante ou invalide.
curl --request GET "https://api.temp-number.com/v1/numbers?status=expiring_soon" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "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 obligatoire

Acheter un numéro

Attribue un nouveau numéro privé et débite votre portefeuille en une seule étape atomique. Si l'attribution échoue après le débit, celui-ci est annulé : vous ne payez jamais sans recevoir de numéro. La réponse indique le montant débité et votre solde restant.

Paramètres
  • country_code string body Obligatoire

    Un pays issu de GET /pricing.

  • duration enum body Obligatoire

    Une clé de durée issue du packages[] de ce pays - chaque pays propose ses propres durées.

    L'un de halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body Facultatif

    Omettez-le pour utiliser la valeur par défaut de la route.

    L'un de voipnon_voip
  • Idempotency-Key string header Obligatoire

    Un UUID, nouveau pour chaque achat, réutilisé lors des nouvelles tentatives.

Renvoie

Le nouvel objet numéro dans data ; meta.charged, meta.currency, meta.wallet_balance_after.

Erreurs
  • 422insufficient_fundsLe solde du portefeuille ne couvre pas le prix.
  • 422out_of_stockÉpuisé depuis votre vérification du stock.
  • 422invalid_durationDurée non proposée pour ce pays/type.
  • 403kyc_requiredVérification d'identité requise au préalable. Aucun débit effectué.
  • 503purchases_pausedAchats suspendus sur toute la plateforme. 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"}'
Réponse
{
  "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 obligatoire

Renouveler un numéro

Prolonge un numéro selon la formule choisie. La nouvelle durée s'ajoute à l'expiration actuelle : renouveler en avance ne fait rien perdre. Le prix est le tarif actuel du site, calculé de notre côté. Les numéros expirés ne peuvent pas être renouvelés : achetez-en un nouveau.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • package enum body Facultatif

    Durée du renouvellement. Par défaut oneMonth. (duration est accepté comme ancien alias.)

    L'un de oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header Obligatoire

    Un UUID, nouveau pour chaque renouvellement, réutilisé lors des nouvelles tentatives.

Renvoie

L'objet numéro mis à jour dans data ; meta.charged, meta.currency, meta.wallet_balance_after.

Erreurs
  • 404Ce numéro n'appartient pas à votre compte.
  • 422insufficient_fundsLe solde du portefeuille ne couvre pas le renouvellement.
  • 422Expiré, annulé ou non renouvelable.
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"}'
Réponse
{
  "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 obligatoire

Annuler un numéro pour être remboursé

Libère un numéro et rembourse son prix intégral sur votre portefeuille. Autorisé uniquement entre 15 et 120 minutes après l'achat, tant que le numéro est actif et n'a reçu aucun SMS. En dehors de ces règles, l'appel est refusé avec 422 et rien ne change ; si c'est trop tôt, details.seconds_until_open indique combien de temps attendre.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • Idempotency-Key string header Obligatoire

    Un UUID, réutilisé lors des nouvelles tentatives.

Renvoie

L'objet numéro (status cancelled) dans data ; meta.refunded, meta.currency, meta.wallet_balance_after.

Erreurs
  • 404Ce numéro n'appartient pas à votre compte.
  • 422Trop tôt (moins de 15 min), trop tard (plus de 120 min), SMS déjà reçu, ou numéro inactif.
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)"
Réponse
{
  "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

Lisez les SMS reçus par vos numéros. Vous recevez le texte brut ; l'extraction d'un code vous revient.

L'objet message SMS

Un SMS reçu, tel que renvoyé par GET /numbers/{id}/sms. (GET /receive-sms utilise une variante en camelCase, présentée sur cet endpoint.)

Champs
  • idinteger

    Id du message.

  • fromstring

    Expéditeur : un numéro de téléphone ou un nom comme WhatsApp.

  • bodystring

    Le texte complet du message.

  • received_atstring

    ISO 8601, UTC.

Alias obsolètes encore envoyés : sender (= from) et message (= body).

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

Obtenir un numéro et ses SMS

Un numéro avec tous les SMS qu'il a reçus, du plus récent au plus ancien. Idéal pour une vue détaillée d'un numéro et pour interroger un seul numéro en attendant un code. Les ids qui ne vous appartiennent pas renvoient 404.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

Renvoie

data.number (un objet numéro) et data.messages (objets message SMS) ; meta.count.

Erreurs
  • 404Ce numéro n'appartient pas à votre compte.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "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

Recevoir des SMS par numéro de téléphone

SMS paginés par curseur pour un numéro qui vous appartient, identifié par son numéro de téléphone plutôt que par son id. Idéal pour les boîtes de réception à fort volume. Un numéro qui ne vous appartient pas renvoie 403.

Paramètres
  • phoneNumber string query Obligatoire

    Format E.164 ou chiffres uniquement, par ex. +14035551234. Encodez le + dans l'URL.

  • limit integer query Facultatif

    Taille de page de 1 à 100. Par défaut 50.

  • cursor string query Facultatif

    meta.nextCursor de la page précédente.

Champs de la réponse
  • data.messages[].idinteger

    Id du message.

  • data.messages[].fromstring

    Expéditeur.

  • data.messages[].tostring

    Votre numéro.

  • data.messages[].messagestring

    Le texte complet.

  • data.messages[].receivedAtstring

    ISO 8601.

  • meta.hasMore / nextCursorboolean / string | null

    Passez nextCursor comme cursor pour obtenir la page suivante.

Erreurs
  • 403Ce numéro n'appartient pas à votre compte.
  • 422phoneNumber manquant ou invalide.
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"
Réponse
{
  "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"
  }
}

E-mail privé

Une boîte de réception [email protected] gratuite, en réception seule, pour chaque numéro privé. Une adresse par numéro.

L'objet e-mail privé

La boîte de réception associée à un numéro.

Champs
  • addressstring | null

    L'adresse, ou null avant qu'elle ne soit réclamée.

  • statusenum

    active ou none.

  • unread_countinteger

    E-mails non lus.

  • created_atstring | null

    Quand l'adresse a été réclamée.

  • eligibleboolean

    Vrai lorsque le numéro peut réclamer une adresse dès maintenant.

  • linked_numberstring

    Le numéro de téléphone auquel il appartient.

  • domainstring

    privnum.com

  • suggestionsstring[]

    Suggestions de noms tant que le numéro est éligible.

objet
{
  "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

Obtenir l'e-mail privé

L'adresse d'un numéro ou, avant qu'elle ne soit réclamée, s'il peut en avoir une ainsi que quelques suggestions de noms.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

Renvoie

Un objet e-mail privé dans data.

Erreurs
  • 404Ce numéro n'appartient pas à votre compte.
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
Réponse
{
  "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

Vérifier un nom

Vérification en direct qu'un nom est valide et libre avant de le réclamer.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • local_part string query Obligatoire

    La partie avant le @ : 3 à 64 lettres, chiffres, points, tirets ou tirets bas.

Champs de la réponse
  • availableboolean

    Vrai lorsque vous pouvez le réclamer.

  • reasonenum | null

    too_short, too_long, invalid, reserved ou taken.

Erreurs
  • 404Ce numéro n'appartient pas à votre compte.
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"
Réponse
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /v1/numbers/{id}/private-email

Réclamer une adresse

Attribue son adresse à un numéro actif. Gratuit, une par numéro, et une adresse réclamée n'est jamais attribuée à quelqu'un d'autre.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • local_part string body Obligatoire

    Le nom que vous avez vérifié.

Renvoie

L'objet e-mail privé dans data.

Erreurs
  • 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
  • 422Nom déjà pris ou invalide (details.reason), le numéro a déjà une adresse, ou il n'est pas actif.
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"}'
Réponse
{
  "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

Lister les e-mails

Résumés des e-mails, du plus récent au plus ancien, avec pagination par page et le nombre de non-lus au niveau supérieur.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • page integer query Facultatif

    Numéro de page. Par défaut 1.

  • per_page integer query Facultatif

    1 à 100. Par défaut 25.

Champs de la réponse
  • 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

    Au niveau supérieur, à côté de data.

Erreurs
  • 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
  • 404private_email_closedLe numéro a été annulé ou remboursé.
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"
Réponse
{
  "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

Lire un e-mail

L'e-mail complet (HTML et texte) avec la liste de ses pièces jointes. Le lire le marque comme lu.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • messageId integer path Obligatoire

    Id de l'e-mail issu de la liste de la boîte de réception.

Erreurs
  • 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
  • 404private_email_closedLe numéro a été annulé ou remboursé.
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"
Réponse
{
  "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}

Télécharger une pièce jointe

Le fichier brut, avec son propre Content-Type et son nom de fichier. index provient de attachments[] de l'e-mail.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • messageId integer path Obligatoire

    Id de l'e-mail issu de la liste de la boîte de réception.

  • index integer path Obligatoire

    attachments[].index issu de « Lire un e-mail ».

Erreurs
  • 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
  • 404private_email_closedLe numéro a été annulé ou remboursé.
  • 404Aucune pièce jointe à cet index.
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
Réponse
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}

Supprimer un e-mail

Supprime l'e-mail et ses pièces jointes.

Paramètres
  • id integer path Obligatoire

    Id du numéro issu de GET /numbers.

  • messageId integer path Obligatoire

    Id de l'e-mail issu de la liste de la boîte de réception.

Erreurs
  • 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
  • 404private_email_closedLe numéro a été annulé ou remboursé.
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"
Réponse
{
  "success": true,
  "data": null
}

IA et MCP

Laissez un assistant IA utiliser directement votre compte, ou donnez à un agent de code tout ce dont il a besoin pour développer avec l'API.

Serveur MCP

En plus de l'API REST, nous proposons un serveur Model Context Protocol. Connectez-le à Claude, ChatGPT ou à votre éditeur, et l'assistant pourra consulter les prix et le stock, acheter un numéro et lire ses SMS grâce à des outils natifs, sans aucun code de votre côté. Vous découvrez MCP ? Commencez par la présentation du serveur MCP.

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

Fonctionnement de la connexion

  • Ajoutez l'URL à votre application d'IA. Elle vous redirige vers Temp Number pour vous connecter avec votre propre compte (OAuth 2.1 avec PKCE) - aucune clé à copier.
  • Sur l'écran de consentement, vous choisissez ce que l'assistant peut faire. La lecture du solde, des prix, de vos numéros et de leurs SMS est toujours incluse. Autoriser les achats - acheter, renouveler et annuler avec votre portefeuille - reste désactivé tant que vous ne le cochez pas.
  • Chaque connexion est listée dans Tableau de bord → Serveur MCP → Applications connectées, où vous pouvez la déconnecter à tout moment.
  • Vous préférez une clé (CI, scripts, agents headless) ? Créez une clé MCP sur la même page et envoyez-la dans Authorization: Bearer <key>. Les clés MCP et les clés de l'API REST ne sont pas interchangeables.

Outils

OutilCe qu'il faitNécessite « Autoriser les achats »
get-balanceRécupérer le solde du portefeuille du compte authentifié et la devise de facturation.Non
get-pricingRenvoyer le catalogue de prix actif pour tous les pays ou pour un seul code pays ISO.Non
get-inventoryConsulter la disponibilité du stock en temps réel pour un pays, une durée et un type de numéro facultatif.Non
purchase-numberAcheter un numéro privé pour le compte authentifié avec les fonds du portefeuille.Oui
list-active-numbersRenvoyer les numéros appartenant au compte authentifié, éventuellement filtrés par statut.Non
check-smsRécupérer les SMS d'un numéro acheté (par ID) appartenant au compte authentifié.Non
renew-numberRenouveler un numéro acheté par son ID avec un forfait de durée facultatif.Oui
cancel-numberAnnuler un numéro acheté par son ID et restituer le remboursement éligible sur le portefeuille.Oui

Connectez votre outil d'IA

Choisissez votre application. La plupart se connectent en un clic : vous vous connectez à Temp Number, cochez ce que l'assistant peut faire, puis cliquez sur Allow.

Claude - claude.ai, ordinateur et mobile

Rien à installer. Fonctionne dans le navigateur, l'application de bureau et sur mobile.

  1. Cliquez sur Ajouter à Claude. Claude s'ouvre avec Temp Number et son URL déjà renseignés. Cliquez sur Add.
  2. Cliquez sur Connect, connectez-vous à Temp Number, choisissez si Claude peut effectuer des achats, puis cliquez sur Allow.
  3. Dans n'importe quelle conversation, ouvrez le menu + → Connectors et activez Temp Number. Essayez : « Combien coûte un numéro américain pour un mois ? »
Team et Enterprise : un propriétaire ajoute le connecteur une seule fois dans Paramètres de l'organisation → Connecteurs. Chaque membre se connecte ensuite avec son propre compte Temp Number, et chacun dépense depuis son propre portefeuille.

Pas de bouton ? Dans Claude, allez dans Customize → Connectors → Add custom connector et collez l'endpoint MCP. Les organisations disposant de l'option d'en-tête de requête de Claude peuvent envoyer une clé MCP dans Authorization: Bearer <key> au lieu de se connecter.

llms.txt et prompt pour agent

Vous développez avec un assistant de code IA ? Donnez-lui le contexte ci-dessous et il pourra intégrer l'API correctement du premier coup - authentification, idempotence et limites de débit comprises.

llms.txt Spécification 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 est un résumé en texte brut, toujours à jour, de chaque endpoint ; la spécification OpenAPI en est le contrat typé. Les deux évoluent avec l'API.

Ressources

Ce qui a changé, et où obtenir de l'aide.

Journal des modifications

Changements additifs uniquement - rien n'a été supprimé de /v1.

  • NewMCP : connectez-vous avec votre compte Temp Number

    « Add to Claude » en un clic, ainsi que ChatGPT, Claude Code, Codex, Cursor et VS Code sans copier de clé. Vous choisissez sur l'écran de consentement si l'IA peut dépenser.

  • DocsUn nouvel espace pour la documentation

    Démarrage rapide, recherche et tous les exemples en cURL, Node.js, Python et PHP. Les erreurs, les limites de débit et les remboursements correspondent désormais exactement à l'API en production.

  • Newllms.txt pour l'ensemble du site

    Une description en texte brut du service destinée aux assistants IA, avec un lien vers la référence API adaptée aux agents.

  • NewConnectez votre outil d'IA

    Configuration pour Claude Code, Codex, Cursor et VS Code, avec des liens d'installation en un clic pour Cursor et VS Code.

  • NewSpécification OpenAPI

    Le contrat lisible par machine est disponible à l'adresse https://api.temp-number.com/api.json.

  • ImprovedLes objets correspondent à la référence

    Les numéros et les SMS utilisent des dates ISO 8601 et from/body. Les erreurs comportent un code lisible par machine (out_of_stock, insufficient_funds, invalid_duration). /inventory renvoie tous les types de numéros si vous omettez number_type. Les anciens noms de champs fonctionnent toujours comme alias obsolètes.

  • NewEndpoints de l'e-mail privé

    Réclamez une boîte de réception [email protected] gratuite pour un numéro, lisez les e-mails et téléchargez les pièces jointes via l'API.

  • NewServeur MCP

    Les agents IA peuvent consulter les prix, acheter des numéros et lire les SMS comme des outils, avec une clé MCP.

  • LaunchAPI REST publique v1

    Compte, tarifs, stock, cycle de vie des numéros et SMS, avec authentification par jeton Bearer.

Support

Bloqué, ou vous avez trouvé dans cette documentation quelque chose qui ne correspond pas au comportement de l'API ? Contactez-nous - indiquez l'endpoint, l'heure de la requête et le corps de la réponse (jamais votre clé API).

Prêt à vous lancer ?

Créez une clé et effectuez votre premier appel en moins d'une minute.

Connectez-vous pour commencer