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.
https://api.temp-number.com/v1
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.
Démarrage rapide
De zéro à un code de vérification. Choisissez votre langage une fois - tous les exemples de la page suivront.
-
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. -
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"const response = await fetch("https://api.temp-number.com/v1/account", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/account", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/account'); $result = $response->json(); -
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"const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/inventory", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, params={"country_code": "US", "duration": "oneMonth"}, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/inventory', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
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"}'import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/buy", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ country_code: "US", duration: "oneMonth" }), }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/buy", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, json={"country_code": "US", "duration": "oneMonth"}, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/buy', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
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"const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/numbers/1482/sms", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/numbers/1482/sms'); $result = $response->json(); -
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)"import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Idempotency-Key": randomUUID(), }, }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/1482/cancel", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/1482/cancel'); $result = $response->json();
Authentification
Envoyez votre clé API dans l'en-tête standard Authorization avec chaque requête :
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, renvoie403avec lecodeemail_unverifiedouaccount_suspended. - Les clés REST fonctionnent uniquement sur
/v1. Le serveur MCP utilise sa propre connexion ou des clés MCP - voir Serveur MCP.
URL de base et versions
Tous les endpoints se trouvent sous le préfixe permanent /v1 :
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, etAccept: application/jsonavec chaque requête. - Succès :
{ "success": true, "data": …, "meta": {…} }.metacontient les décomptes, la pagination et les récapitulatifs financiers. - Erreurs :
{ "success": false, "message": "…", "code": "…" }. Basez votre logique surcode; 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.
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.
{
"success": false,
"message": "Insufficient wallet balance.",
"code": "insufficient_funds"
}
{
"message": "The country code field is required.",
"errors": {
"country_code": ["The country code field is required."]
}
}
| Statut | code | Signification | Que 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 à | Limite | Comptabilisé |
|---|---|---|
| Tous les endpoints | 60 / minute | par clé API |
| Acheter, renouveler, annuler | 10 / minute | par compte, en plus des limites ci-dessus |
| GET /receive-sms | 60 / minute | par clé API |
| GET /receive-sms | 30 / minute | par clé API et numéro de téléphone |
| GET /receive-sms | 30 / minute | par 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.
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.
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.
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.
/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-
balancenumberSolde disponible du portefeuille.
-
currencystringDevise de règlement, USD.
- 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"
const response = await fetch("https://api.temp-number.com/v1/account", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/account",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/account');
$result = $response->json();
{
"success": true,
"balance": 124.50,
"currency": "USD"
}
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_codestringCode ISO 3166-1 alpha-2, par ex. US.
-
country_namestringNom affiché.
-
packages[].number_typeenumvoip ou non_voip.
-
packages[].durationenumLa clé à envoyer pour acheter : halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths ou oneYear. Chaque pays propose ses propres durées.
-
packages[].duration_labelstringLibellé lisible, par ex. "1 Month".
-
packages[].pricenumberPrix final en USD.
-
packages[].original_pricenumber | nullLe prix avant remise, lorsqu'une remise s'applique.
-
packages[].updated_atnullRéservé.
{
"country_code": "US",
"country_name": "United States",
"packages": [
{
"number_type": "voip",
"duration": "oneMonth",
"duration_label": "1 Month",
"price": 4.99,
"original_price": 5.99,
"updated_at": null
}
]
}
/v1/pricing
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.
RenvoieUne 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"
const response = await fetch("https://api.temp-number.com/v1/pricing", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing');
$result = $response->json();
{
"success": true,
"data": [
{
"country_code": "US",
"country_name": "United States",
"packages": [
{
"number_type": "voip",
"duration": "oneMonth",
"duration_label": "1 Month",
"price": 4.99,
"original_price": 5.99,
"updated_at": null
},
{
"number_type": "voip",
"duration": "threeMonths",
"duration_label": "3 Months",
"price": 12.99,
"original_price": null,
"updated_at": null
}
]
}
],
"meta": { "count": 1 }
}
/v1/pricing/{countryCode}
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-
countryCodestring path ObligatoireCode pays ISO 3166-1 alpha-2, par ex. US, GB, CA.
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"
const response = await fetch("https://api.temp-number.com/v1/pricing/GB", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing/GB",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing/GB');
$result = $response->json();
{
"success": true,
"data": {
"country_code": "GB",
"country_name": "United Kingdom",
"packages": [
{
"number_type": "voip",
"duration": "oneMonth",
"duration_label": "1 Month",
"price": 5.49,
"original_price": null,
"updated_at": null
}
]
}
}
/v1/inventory
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_codestring query ObligatoireCode pays ISO 3166-1 alpha-2.
-
durationenum query FacultatifUne clé de durée issue de GET /pricing/{countryCode}. Omettez-la pour utiliser la valeur par défaut de la route.
L'un dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query FacultatifLimitez la vérification à un type. Omettez-le pour voir tous les types.
L'un devoipnon_voip
-
stockinteger | nullNuméros disponibles (additionnés sur types[] lorsque number_type est omis).
-
availablebooleanVrai lorsqu'au moins un numéro peut être acheté.
-
statusstringLibellé lisible : In Stock, Out of Stock, Coming Soon…
-
types[]arrayUniquement lorsque number_type est omis : number_type, stock, available, status pour chaque type vendu sur ce marché.
- 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"
const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/inventory",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"country_code": "US", "duration": "oneMonth"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/inventory', [
'country_code' => 'US',
'duration' => 'oneMonth',
]);
$result = $response->json();
{
"success": true,
"data": {
"country_code": "US",
"duration": "oneMonth",
"number_type": null,
"stock": 47,
"available": true,
"status": "In Stock",
"types": [
{ "number_type": "voip", "stock": 0, "available": false, "status": "Out of Stock" },
{ "number_type": "non_voip", "stock": 47, "available": true, "status": "In Stock" }
]
}
}
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-
idintegerUtilisez-le dans les appels /numbers/{id}/…. Les webhooks l'envoient sous number.rentalId.
-
phone_numberstringFormat E.164, par ex. +14035551234.
-
country_codestring | nullISO 3166-1 alpha-2.
-
country_namestringNom affiché.
-
number_typeenumvoip ou non_voip.
-
statusenumactive, expired, cancelled ou refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 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.
{
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "active",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-06-13T17:42:09Z"
}
/v1/numbers
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-
statusenum query FacultatifFiltre de cycle de vie. Par défaut all.
L'un deallactiveexpiring_soonexpiredcancelled
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"
const response = await fetch("https://api.temp-number.com/v1/numbers?status=expiring_soon", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"status": "expiring_soon"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers', [
'status' => 'expiring_soon',
]);
$result = $response->json();
{
"success": true,
"data": [
{
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "active",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-06-13T17:42:09Z"
}
],
"meta": { "count": 1, "status": "expiring_soon" }
}
/v1/numbers/buy
Idempotency-Key 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_codestring body ObligatoireUn pays issu de GET /pricing.
-
durationenum body ObligatoireUne clé de durée issue du packages[] de ce pays - chaque pays propose ses propres durées.
L'un dehalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body FacultatifOmettez-le pour utiliser la valeur par défaut de la route.
L'un devoipnon_voip -
Idempotency-Keystring header ObligatoireUn UUID, nouveau pour chaque achat, réutilisé lors des nouvelles tentatives.
Le nouvel objet numéro dans data ; meta.charged, meta.currency, meta.wallet_balance_after.
Erreurs- 422
insufficient_fundsLe solde du portefeuille ne couvre pas le prix. - 422
out_of_stockÉpuisé depuis votre vérification du stock. - 422
invalid_durationDurée non proposée pour ce pays/type. - 403
kyc_requiredVérification d'identité requise au préalable. Aucun débit effectué. - 503
purchases_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/buy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ country_code: "US", duration: "oneMonth", number_type: "voip" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/buy",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"country_code": "US", "duration": "oneMonth", "number_type": "voip"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/buy', [
'country_code' => 'US',
'duration' => 'oneMonth',
'number_type' => 'voip',
]);
$result = $response->json();
{
"success": true,
"data": {
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "active",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-06-13T17:42:09Z"
},
"meta": {
"charged": 4.99,
"currency": "USD",
"wallet_balance_after": 119.51
}
}
/v1/numbers/{id}/renew
Idempotency-Key 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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
packageenum body FacultatifDurée du renouvellement. Par défaut oneMonth. (duration est accepté comme ancien alias.)
L'un deoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header ObligatoireUn UUID, nouveau pour chaque renouvellement, réutilisé lors des nouvelles tentatives.
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.
- 422
insufficient_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/renew", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ package: "threeMonths" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/renew",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"package": "threeMonths"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/renew', [
'package' => 'threeMonths',
]);
$result = $response->json();
{
"success": true,
"data": {
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "active",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-09-13T17:42:09Z"
},
"meta": {
"charged": 12.99,
"currency": "USD",
"wallet_balance_after": 106.52
}
}
/v1/numbers/{id}/cancel
Idempotency-Key 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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
Idempotency-Keystring header ObligatoireUn UUID, réutilisé lors des nouvelles tentatives.
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)"
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Idempotency-Key": randomUUID(),
},
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/cancel",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/cancel');
$result = $response->json();
{
"success": true,
"data": {
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "cancelled",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-06-13T17:42:09Z"
},
"meta": {
"refunded": 4.99,
"currency": "USD",
"wallet_balance_after": 124.50
}
}
SMS
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-
idintegerId du message.
-
fromstringExpéditeur : un numéro de téléphone ou un nom comme WhatsApp.
-
bodystringLe texte complet du message.
-
received_atstringISO 8601, UTC.
Alias obsolètes encore envoyés : sender (= from) et message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/sms');
$result = $response->json();
{
"success": true,
"data": {
"number": {
"id": 1482,
"phone_number": "+14035551234",
"country_code": "US",
"country_name": "United States",
"number_type": "voip",
"status": "active",
"purchase_date": "2026-05-13T17:42:09Z",
"expire_date": "2026-06-13T17:42:09Z"
},
"messages": [
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
]
},
"meta": { "count": 1 }
}
/v1/receive-sms
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-
phoneNumberstring query ObligatoireFormat E.164 ou chiffres uniquement, par ex. +14035551234. Encodez le + dans l'URL.
-
limitinteger query FacultatifTaille de page de 1 à 100. Par défaut 50.
-
cursorstring query Facultatifmeta.nextCursor de la page précédente.
-
data.messages[].idintegerId du message.
-
data.messages[].fromstringExpéditeur.
-
data.messages[].tostringVotre numéro.
-
data.messages[].messagestringLe texte complet.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullPassez nextCursor comme cursor pour obtenir la page suivante.
- 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"
const response = await fetch("https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/receive-sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"phoneNumber": "+14035551234", "limit": 50},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/receive-sms', [
'phoneNumber' => '+14035551234',
'limit' => 50,
]);
$result = $response->json();
{
"success": true,
"data": {
"phoneNumber": "+14035551234",
"purchaseStatus": "active",
"messages": [
{
"id": 1842,
"from": "WhatsApp",
"to": "+14035551234",
"message": "Your verification code is 483920.",
"receivedAt": "2026-05-13T17:43:14+00:00"
}
]
},
"meta": {
"count": 1,
"pageSize": 50,
"hasMore": false,
"nextCursor": null,
"prevCursor": null,
"requestedAt": "2026-05-13T17:43:20+00:00"
}
}
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 | nullL'adresse, ou null avant qu'elle ne soit réclamée.
-
statusenumactive ou none.
-
unread_countintegerE-mails non lus.
-
created_atstring | nullQuand l'adresse a été réclamée.
-
eligiblebooleanVrai lorsque le numéro peut réclamer une adresse dès maintenant.
-
linked_numberstringLe numéro de téléphone auquel il appartient.
-
domainstringprivnum.com
-
suggestionsstring[]Suggestions de noms tant que le numéro est éligible.
{
"address": "[email protected]",
"status": "active",
"unread_count": 2,
"created_at": "2026-07-03T10:15:00+00:00",
"eligible": false,
"linked_number": "+14035551234",
"domain": "privnum.com",
"suggestions": []
}
/v1/numbers/{id}/private-email
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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email');
$result = $response->json();
{
"success": true,
"data": {
"address": null,
"status": "none",
"unread_count": 0,
"created_at": null,
"eligible": true,
"linked_number": "+14035551234",
"domain": "privnum.com",
"suggestions": ["alex.smith", "alex.smith42"]
}
}
/v1/numbers/{id}/private-email/availability
Vérifier un nom
Vérification en direct qu'un nom est valide et libre avant de le réclamer.
Paramètres-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
local_partstring query ObligatoireLa partie avant le @ : 3 à 64 lettres, chiffres, points, tirets ou tirets bas.
-
availablebooleanVrai lorsque vous pouvez le réclamer.
-
reasonenum | nulltoo_short, too_long, invalid, reserved ou taken.
- 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/availability",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"local_part": "alex.smith"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/availability', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"success": true,
"data": {
"local_part": "alex.smith",
"address": "[email protected]",
"available": true,
"reason": null,
"message": "Available"
}
}
/v1/numbers/{id}/private-email
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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
local_partstring body ObligatoireLe nom que vous avez vérifié.
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"}'
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({ local_part: "alex.smith" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
json={"local_part": "alex.smith"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/private-email', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"success": true,
"data": {
"address": "[email protected]",
"status": "active",
"unread_count": 0,
"created_at": "2026-07-03T10:15:00+00:00",
"eligible": false,
"linked_number": "+14035551234",
"domain": "privnum.com",
"suggestions": []
}
}
/v1/numbers/{id}/private-email/inbox
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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
pageinteger query FacultatifNuméro de page. Par défaut 1.
-
per_pageinteger query Facultatif1 à 100. Par défaut 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerAu niveau supérieur, à côté de data.
- 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"page": 1, "per_page": 25},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox', [
'page' => 1,
'per_page' => 25,
]);
$result = $response->json();
{
"success": true,
"data": [
{
"id": 77,
"from_email": "[email protected]",
"from_name": "Example Billing",
"subject": "Your receipt",
"preview": "Thanks for your order…",
"attachment_count": 1,
"is_read": false,
"received_at": "2026-07-04T08:01:12+00:00"
}
],
"meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
"unread_count": 1
}
/v1/numbers/{id}/private-email/inbox/{messageId}/body
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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
messageIdinteger path ObligatoireId de l'e-mail issu de la liste de la boîte de réception.
- 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body');
$result = $response->json();
{
"success": true,
"data": {
"id": 77,
"subject": "Your receipt",
"from_email": "[email protected]",
"from_name": "Example Billing",
"received_at": "2026-07-04T08:01:12+00:00",
"html": "<p>Thanks for your order…</p>",
"text": "Thanks for your order…",
"attachments": [
{ "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
]
}
}
/v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}
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-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
messageIdinteger path ObligatoireId de l'e-mail issu de la liste de la boîte de réception.
-
indexinteger path Obligatoireattachments[].index issu de « Lire un e-mail ».
- 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
- 404
private_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
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
},
});
await writeFile("receipt.pdf", Buffer.from(await response.arrayBuffer()));
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
},
timeout=30,
)
with open("receipt.pdf", "wb") as file:
file.write(response.content)
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->sink(storage_path('receipt.pdf'))
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0');
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf
<binary file>
/v1/numbers/{id}/private-email/inbox/{messageId}
Supprimer un e-mail
Supprime l'e-mail et ses pièces jointes.
Paramètres-
idinteger path ObligatoireId du numéro issu de GET /numbers.
-
messageIdinteger path ObligatoireId de l'e-mail issu de la liste de la boîte de réception.
- 404Ce n'est pas votre numéro, ou il n'a pas encore d'adresse.
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.delete(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->delete('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77');
$result = $response->json();
{
"success": true,
"data": null
}
IA 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.
Endpointhttps://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
| Outil | Ce qu'il fait | Nécessite « Autoriser les achats » |
|---|---|---|
get-balance | Récupérer le solde du portefeuille du compte authentifié et la devise de facturation. | Non |
get-pricing | Renvoyer le catalogue de prix actif pour tous les pays ou pour un seul code pays ISO. | Non |
get-inventory | Consulter la disponibilité du stock en temps réel pour un pays, une durée et un type de numéro facultatif. | Non |
purchase-number | Acheter un numéro privé pour le compte authentifié avec les fonds du portefeuille. | Oui |
list-active-numbers | Renvoyer les numéros appartenant au compte authentifié, éventuellement filtrés par statut. | Non |
check-sms | Récupérer les SMS d'un numéro acheté (par ID) appartenant au compte authentifié. | Non |
renew-number | Renouveler un numéro acheté par son ID avec un forfait de durée facultatif. | Oui |
cancel-number | Annuler 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.
- Cliquez sur Ajouter à Claude. Claude s'ouvre avec Temp Number et son URL déjà renseignés. Cliquez sur Add.
- Cliquez sur Connect, connectez-vous à Temp Number, choisissez si Claude peut effectuer des achats, puis cliquez sur Allow.
- 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 ? »
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.
ChatGPT
Nécessite ChatGPT Business, Enterprise ou Edu sur le web. Avec Business, c'est un administrateur ou le propriétaire qui l'ajoute.
- Copiez l'URL du serveur ci-dessous, puis cliquez sur Ouvrir ChatGPT pour accéder à sa page Plugins. ChatGPT ne propose aucun lien qui la renseigne pour vous.
- Cliquez sur + → Add custom MCP server. Nommez-le Temp Number et collez l'URL sous Connection.
- Définissez l'authentification sur OAuth, acceptez l'avertissement de risque et cliquez sur Create as a plugin.
- Quand ChatGPT le demande, connectez-vous à Temp Number, choisissez si ChatGPT peut effectuer des achats, puis cliquez sur Allow.
- Dans une nouvelle conversation, tapez @ et choisissez Temp Number. Essayez : « Combien coûte un numéro américain pour un mois ? »
https://mcp.temp-number.com/mcp
Claude Code
Ajoutez le serveur une fois, puis connectez-vous depuis Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Lancez Claude Code et tapez
/mcp. - Choisissez temp-number → Authenticate. Votre navigateur s'ouvre : connectez-vous et cliquez sur Allow.
Utiliser plutôt une clé MCP (CI / headless)
export TEMPNUMBER_MCP_KEY=your-mcp-key
claude mcp add --transport http temp-number \
https://mcp.temp-number.com/mcp \
--header "Authorization: Bearer $TEMPNUMBER_MCP_KEY"
Codex CLI
Ajoutez le serveur, puis connectez-vous. Codex enregistre la session pour vous.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Utiliser plutôt une clé MCP (CI / headless)
Dans ~/.codex/config.toml. La clé est lue depuis l'environnement, le fichier peut donc être partagé sans risque.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Un clic, puis connectez-vous quand Cursor le demande.
Ou ajoutez-le à .cursor/mcp.json (ou ~/.cursor/mcp.json). Cursor affiche alors Needs login à côté du serveur : cliquez dessus, connectez-vous et cliquez sur Allow.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Utiliser plutôt une clé MCP
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Un clic, puis connectez-vous la première fois qu'un outil s'exécute.
Ou ajoutez-le à .vscode/mcp.json - attention, la clé est servers, et non mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Utiliser plutôt une clé MCP
VS Code demande la clé une seule fois et la conserve dans son stockage sécurisé.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${input:tempnumber-mcp-key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "tempnumber-mcp-key",
"description": "Temp Number MCP key",
"password": true
}
]
}
Toute autre application MCP
Windsurf, Zed, LibreChat, votre propre agent…
- Ajoutez l'endpoint MCP comme serveur distant (HTTP streamable). Les applications qui prennent en charge la connexion le trouvent d'elles-mêmes sur
https://mcp.temp-number.com/.well-known/oauth-protected-resourceet ouvrent l'écran de consentement de Temp Number. - Les applications sans prise en charge de la connexion peuvent envoyer une clé MCP dans
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
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.
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.