Temp Number API - Số điện thoại, SMS & OTP
Cấp số điện thoại ảo, nhận SMS theo thời gian thực và tự động hóa xác minh OTP - qua REST API gọn gàng, hoặc trực tiếp từ trợ lý AI của bạn.
https://api.temp-number.com/v1
Trang chủ / Nhà phát triển
Giới thiệu
Temp Number API được tổ chức quanh các tài nguyên dễ đoán, dùng các phương thức HTTP tiêu chuẩn và trả về JSON cho mọi phản hồi. Một khóa cấp quyền đọc và ghi chỉ cho tài khoản của bạn - không có quyền truy cập chéo giữa các tài khoản.
Bắt đầu nhanh
Từ con số không đến mã xác minh. Chọn ngôn ngữ một lần - mọi ví dụ trên trang sẽ theo ngôn ngữ đó.
-
Tạo khóa API
Trong Bảng điều khiển → Truy cập API, hãy tạo một khóa. Khóa chỉ hiển thị một lần: hãy lưu nó vào biến môi trường
TEMP_NUMBER_API_KEY. -
Kiểm tra số dư
Mỗi lệnh gọi đều mang khóa của bạn trong header Authorization. Hãy bắt đầu với thứ vô hại: số dư ví của bạn.
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(); -
Chọn quốc gia và kiểm tra tồn kho
GET /pricing liệt kê mọi quốc gia với giá chính xác theo từng thời hạn. Sau đó xác nhận tồn kho cho quốc gia bạn muốn.
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(); -
Mua số
Gửi một Idempotency-Key mới với mỗi lần mua. Nếu mất kết nối mạng, hãy thử lại với cùng khóa: bạn không bao giờ bị trừ tiền hai lần. Hãy lưu data.id từ phản hồi.
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(); -
Đọc SMS
Thăm dò số mỗi vài giây cho đến khi tin nhắn đến. Bạn nhận văn bản thô; hãy tự trích xuất mã ở phía bạn.
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(); -
Không nhận được SMS? Hủy để được hoàn tiền
Trong khoảng 15 đến 120 phút sau khi mua, số chưa nhận SMS nào có thể được hủy để hoàn toàn bộ tiền vào ví của bạn.
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();
Xác thực
Gửi khóa API trong header Authorization tiêu chuẩn ở mọi yêu cầu:
Authorization: Bearer YOUR_API_KEY
- Tạo khóa trong Truy cập API. Khóa chỉ hiển thị đầy đủ một lần, khi tạo.
- Dùng một khóa cho mỗi tích hợp để bạn có thể thu hồi một khóa mà không ảnh hưởng đến các khóa khác. Đổi mật khẩu sẽ thu hồi mọi khóa.
- Khóa bị thiếu, sai định dạng hoặc đã thu hồi sẽ trả về
401. Tài khoản chưa xác minh email hoặc bị đình chỉ sẽ trả về403vớicodeemail_unverifiedhoặcaccount_suspended. - Khóa REST chỉ hoạt động trên
/v1. Máy chủ MCP dùng cơ chế đăng nhập riêng hoặc khóa MCP - xem Máy chủ MCP.
URL gốc & phiên bản
Mọi endpoint đều nằm dưới tiền tố cố định /v1:
https://api.temp-number.com/v1
Các thay đổi bổ sung - trường, endpoint mới hoặc tham số tùy chọn - được phát hành mà không tăng phiên bản, vì vậy hãy bỏ qua các trường bạn không biết. Thay đổi phá vỡ tương thích sẽ được phát hành dưới /v2; tích hợp của bạn không bao giờ bị chuyển đổi âm thầm. Hợp đồng dạng máy đọc được là đặc tả OpenAPI.
Yêu cầu & phản hồi
- Gửi nội dung JSON với
Content-Type: application/json, vàAccept: application/jsontrong mọi yêu cầu. - Thành công:
{ "success": true, "data": …, "meta": {…} }.metachứa số lượng, thông tin phân trang và tổng hợp số tiền. - Lỗi:
{ "success": false, "message": "…", "code": "…" }. Hãy rẽ nhánh xử lý theocode; message dành cho người đọc. Xem Lỗi. - Thời gian theo chuẩn ISO 8601. Số tiền tính bằng USD với hai chữ số thập phân - luôn là giá bạn trả.
- Một số đối tượng vẫn giữ tên trường cũ cho các tích hợp hiện có (được đánh dấu deprecated trong tài liệu tham chiếu). Mã mới nên bỏ qua chúng.
Lỗi
Lỗi dùng mã trạng thái HTTP tiêu chuẩn. Lỗi nghiệp vụ có code ổn định, máy đọc được; một số lỗi có thêm details với ngữ cảnh chi tiết hơn.
{
"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."]
}
}
| Trạng thái | code | Ý nghĩa | Cần làm gì |
|---|---|---|---|
| 400 | - | Header Idempotency-Key bị thiếu hoặc sai định dạng khi mua, gia hạn hoặc hủy. Nội dung: {"error": "Missing Idempotency-Key header."} | Gửi một UUID trong Idempotency-Key. |
| 401 | - | Không có bearer token, token sai định dạng hoặc khóa đã bị thu hồi. | Kiểm tra header Authorization; tạo khóa mới nếu khóa đã bị thu hồi. |
| 403 | email_unverified |
Tài khoản chưa xác minh địa chỉ email. | Xác minh email trên trang web, rồi thử lại. |
| 403 | account_suspended |
Tài khoản đang bị đình chỉ. | Liên hệ bộ phận hỗ trợ. |
| 403 | kyc_required |
Tài khoản phải xác minh danh tính trước khi mua số mới. Không có khoản nào bị trừ; gia hạn vẫn hoạt động. | Hoàn tất xác minh danh tính trong Cài đặt tài khoản, rồi thử lại. |
| 403 | - | Khóa không có quyền truy cập API (ví dụ khóa MCP), hoặc GET /receive-sms được hỏi về một số thuộc tài khoản khác. | Dùng khóa REST API; chỉ truy vấn số của chính bạn. |
| 404 | - | Số, tin nhắn hoặc quốc gia không thuộc tài khoản của bạn hoặc hiện không mở bán. Id của tài khoản khác cũng trả về 404. | Liệt kê lại bằng GET /numbers hoặc GET /pricing. |
| 404 | private_email_closed |
Hộp thư riêng đã đóng vì số của nó đã bị hủy hoặc hoàn tiền. | Không có gì để thử lại. |
| 409 | - | Idempotency-Key đã được dùng với nội dung khác, hoặc yêu cầu đầu tiên dùng khóa đó vẫn đang chạy. | Dùng khóa mới cho yêu cầu mới; chờ rồi thử lại với yêu cầu đang xử lý. |
| 422 | insufficient_funds |
Ví không đủ tiền để trả giá này. | Nạp tiền vào ví và thử lại. |
| 422 | out_of_stock |
Thị trường đã hết hàng giữa lúc bạn kiểm tra giá và lúc mua. | Kiểm tra lại GET /inventory và chọn thời hạn hoặc loại khác. |
| 422 | invalid_duration |
Thời hạn này không được bán cho quốc gia và loại số đó. | Lấy lại GET /pricing/{countryCode}. |
| 422 | - | Xác thực thất bại (đối tượng `errors` nêu tên từng trường) hoặc một quy tắc đã từ chối hành động, chẳng hạn hủy ngoài thời hạn hoàn tiền. | Đọc `message`; sửa yêu cầu thay vì thử lại. |
| 429 | - | Đã đạt giới hạn tần suất. | Chờ theo header Retry-After, rồi thử lại với backoff. |
| 503 | purchases_paused |
Việc mua mới đang tạm dừng trên toàn nền tảng. Không có khoản nào bị trừ; gia hạn và hủy vẫn hoạt động. | Thử lại sau Retry-After (60 giây). |
| 5xx | - | Đã xảy ra lỗi ở phía chúng tôi. | Thử lại với CÙNG Idempotency-Key - bạn sẽ không bao giờ bị trừ tiền hai lần. |
Giới hạn tốc độ
Giới hạn áp dụng theo từng khóa, và các lệnh gọi liên quan đến tiền còn có thêm giới hạn chặt hơn theo từng tài khoản:
| Áp dụng cho | Giới hạn | Được tính |
|---|---|---|
| Mọi endpoint | 60 / phút | mỗi khóa API |
| Mua, gia hạn, hủy | 10 / phút | mỗi tài khoản, cộng thêm với các giới hạn trên |
| GET /receive-sms | 60 / phút | mỗi khóa API |
| GET /receive-sms | 30 / phút | mỗi khóa API và số điện thoại |
| GET /receive-sms | 30 / phút | mỗi địa chỉ IP |
Khi vượt giới hạn, bạn sẽ nhận 429 kèm header Retry-After (tính bằng giây). Hãy chờ ít nhất khoảng thời gian đó, sau đó thử lại với độ trễ tăng dần kèm jitter. Phản hồi cũng kèm X-RateLimit-Limit và X-RateLimit-Remaining.
Tính lũy đẳng (Idempotency)
POST /numbers/buy, /renew và /cancel bắt buộc có header Idempotency-Key: một UUID bạn tạo cho mỗi thao tác mới. Nếu mất kết nối mạng, hãy gửi lại cùng yêu cầu với cùng khóa - bạn sẽ nhận lại phản hồi ban đầu (được đánh dấu X-Idempotency-Replayed: true) và không bao giờ bị tính phí hai lần.
- Thiếu khóa:
400. Khóa dài tối đa 128 ký tự gồm chữ cái, chữ số,- _ . : - Cùng khóa nhưng nội dung khác:
409. Cùng khóa khi yêu cầu đầu tiên vẫn đang chạy:409- hãy chờ một chút rồi thử lại. - Khóa được ghi nhớ theo từng tài khoản và endpoint. Không bao giờ dùng lại một khóa cho giao dịch mua khác.
Phân trang
GET /receive-sms dùng phân trang theo cursor, mới nhất trước. Đọc meta.hasMore; khi giá trị này là true, gửi lại meta.nextCursor dưới dạng cursor với cùng phoneNumber. Cursor là giá trị không minh bạch (opaque) - không tự tạo hoặc chỉnh sửa chúng.
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9
Các danh sách vốn nhỏ (/numbers, /pricing) trả về toàn bộ trong một phản hồi; hộp thư riêng dùng page và per_page.
Chính sách sử dụng hợp lệ
API được xây dựng cho nhà phát triển: luồng xác minh và OTP, quy trình onboarding tự động, QA và kiểm thử hệ thống, cùng mọi sản phẩm cần nhận SMS hoặc số điện thoại ở quy mô lớn.
- Chỉ dùng cho mục đích xác minh hợp pháp, phát triển và kiểm thử.
- Không lừa đảo, spam, gian lận hay lừa gạt. Các số bị dùng để lừa đảo hoặc hoạt động lạm dụng khác sẽ khiến tài khoản bị khóa ngay lập tức mà không cần báo trước, các số liên quan bị hủy và không được hoàn tiền.
- Không dành cho tài khoản được quản lý chặt chẽ hoặc gắn với danh tính. Các số tạm thời dùng chung của chúng tôi không hỗ trợ xác minh SMS cho ngân hàng, thanh toán, tiền mã hóa, cơ quan nhà nước hoặc các dịch vụ khác xác minh danh tính pháp lý của bạn (KYC/AML) - hãy dùng số di động cá nhân của bạn cho những dịch vụ đó.
Tài liệu tham khảo API
Mọi endpoint /v1 đang hoạt động. Yêu cầu hiển thị bên phải theo ngôn ngữ bạn chọn; phản hồi có cấu trúc thực tế.
Tài khoản
Xem số dư ví và đơn vị tiền tệ thanh toán.
/v1/account
Lấy số dư tài khoản
Trả về số dư ví khả dụng và đơn vị tiền tệ. Hãy kiểm tra trước khi mua để có thể dừng sớm với thông báo "nạp tiền" rõ ràng.
Các trường phản hồi-
balancenumberSố dư ví khả dụng.
-
currencystringĐơn vị tiền tệ thanh toán, USD.
- 401Thiếu khóa hoặc khóa không hợp lệ.
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"
}
Giá & tồn kho
Xem các thị trường đang mở, giá chính xác bạn trả theo từng thời hạn và tồn kho theo thời gian thực.
Đối tượng giá theo quốc gia
Một quốc gia và mọi gói bạn có thể mua ở đó. price là số tiền cuối cùng bị trừ từ ví của bạn; chi phí phía nhà cung cấp không bao giờ được tiết lộ.
Trường-
country_codestringMã ISO 3166-1 alpha-2, ví dụ US.
-
country_namestringTên hiển thị.
-
packages[].number_typeenumvoip hoặc non_voip.
-
packages[].durationenumKhóa bạn gửi để mua: halfDay, oneDay, oneWeek, oneMonth, threeMonths, sixMonths hoặc oneYear. Mỗi quốc gia có bộ thời hạn riêng.
-
packages[].duration_labelstringNhãn dễ đọc, ví dụ "1 Tháng".
-
packages[].pricenumberGiá cuối cùng bằng USD.
-
packages[].original_pricenumber | nullGiá trước khi giảm, nếu có giảm giá.
-
packages[].updated_atnullĐã giữ trước.
{
"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
Liệt kê giá cho mọi quốc gia
Toàn bộ danh mục trực tiếp: danh sách đối tượng giá theo quốc gia. Trường price là mức giá cuối cùng cho người dùng bằng USD, đúng bằng số tiền bị trừ từ ví của bạn.
Trả vềDanh sách đối tượng giá theo quốc gia trong data, kèm meta.count.
Lỗi- 401Thiếu khóa hoặc khóa không hợp lệ.
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}
Lấy giá cho một quốc gia
Giá trực tiếp cho một quốc gia. Mã 404 nghĩa là quốc gia đó hiện không có tuyến hoạt động: hãy coi đó là "hết hàng" tạm thời, không phải "không bao giờ bán".
Tham số-
countryCodestring path Bắt buộcMã quốc gia ISO 3166-1 alpha-2, ví dụ US, GB, CA.
Một đối tượng giá quốc gia trong data.
Lỗi- 404Hiện không có tuyến hoạt động cho quốc gia đó.
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
Kiểm tra tồn kho
Tồn kho theo thời gian thực cho một quốc gia và thời hạn, để bạn có thể vô hiệu hóa nút Mua trước khi có ai nhấp vào. Bỏ qua number_type để nhận mọi loại cạnh nhau trong types[]. Kết quả màu xanh là tín hiệu tốt, nhưng chính giao dịch mua mới là bước kiểm tra cuối cùng.
Tham số-
country_codestring query Bắt buộcMã quốc gia ISO 3166-1 alpha-2.
-
durationenum query Không bắt buộcMột khóa thời hạn từ GET /pricing/{countryCode}. Bỏ qua để dùng mặc định của tuyến.
Một tronghalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum query Không bắt buộcGiới hạn việc kiểm tra cho một loại. Bỏ qua để xem tất cả các loại.
Một trongvoipnon_voip
-
stockinteger | nullSố lượng số có sẵn (cộng dồn qua types[] khi bỏ qua number_type).
-
availablebooleanTrue khi có thể mua ít nhất một số.
-
statusstringNhãn dễ đọc: Còn hàng, Hết hàng, Sắp có…
-
types[]arrayChỉ khi bỏ qua number_type: number_type, stock, available, status cho mỗi loại mà thị trường bán.
- 422Không có gì đang bán cho lựa chọn đó; details chứa các trường tồn kho.
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" }
]
}
}
Số
Liệt kê, mua, gia hạn và hủy số riêng của bạn. Các lệnh gọi liên quan đến tiền đều idempotent và an toàn khi gửi lại.
Đối tượng số
Một số trong tài khoản của bạn. Mua, gia hạn và hủy cũng trả về bản tóm tắt tiền trong meta: charged (hoặc refunded), currency và wallet_balance_after.
Trường-
idintegerDùng trong các lệnh gọi /numbers/{id}/…. Webhook gửi nó dưới dạng number.rentalId.
-
phone_numberstringE.164, ví dụ +14035551234.
-
country_codestring | nullISO 3166-1 alpha-2.
-
country_namestringTên hiển thị.
-
number_typeenumvoip hoặc non_voip.
-
statusenumactive, expired, cancelled hoặc refunded.
-
purchase_datestringISO 8601, UTC.
-
expire_datestringISO 8601, UTC. Sau thời điểm này, số ngừng nhận SMS và không thể gia hạn.
Các bí danh đã ngừng hỗ trợ vẫn được gửi cho các tích hợp cũ: country, provider, purchased_at và expires_at (mili giây epoch). Đừng xây dựng dựa trên chúng.
{
"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
Liệt kê số của bạn
Mọi số trong tài khoản của bạn, mới nhất trước. Dùng status=expiring_soon (số đang hoạt động còn trong vòng 10 ngày trước khi hết hạn) để gửi nhắc gia hạn.
Tham số-
statusenum query Không bắt buộcBộ lọc vòng đời. Mặc định all.
Một trongallactiveexpiring_soonexpiredcancelled
Danh sách đối tượng số trong data; meta.count và meta.status.
Lỗi- 401Thiếu khóa hoặc khóa không hợp lệ.
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
Bắt buộc có Idempotency-Key Mua số
Cấp một số riêng mới và trừ tiền ví trong một bước nguyên tử. Nếu việc cấp số thất bại sau khi trừ tiền, khoản trừ sẽ được hoàn lại: bạn không bao giờ mất tiền mà không nhận được số. Phản hồi hiển thị số tiền đã trừ và số dư sau đó.
Tham số-
country_codestring body Bắt buộcMột quốc gia từ GET /pricing.
-
durationenum body Bắt buộcMột khóa thời hạn từ packages[] của quốc gia đó - mỗi quốc gia có bộ thời hạn riêng.
Một tronghalfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body Không bắt buộcBỏ qua để dùng mặc định của tuyến.
Một trongvoipnon_voip -
Idempotency-Keystring header Bắt buộcMột UUID, mới cho mỗi lần mua, dùng lại khi thử lại.
Đối tượng số mới trong data; meta.charged, meta.currency, meta.wallet_balance_after.
Lỗi- 422
insufficient_fundsVí không đủ tiền để trả giá này. - 422
out_of_stockĐã hết hàng kể từ lần kiểm tra tồn kho của bạn. - 422
invalid_durationThời hạn này không được bán cho quốc gia/loại này. - 403
kyc_requiredCần xác minh danh tính trước. Chưa trừ tiền. - 503
purchases_pausedViệc mua đang tạm dừng trên toàn nền tảng. 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
Bắt buộc có Idempotency-Key Gia hạn số
Gia hạn một số theo gói đã chọn. Thời hạn mới được cộng vào thời hạn hiện tại, nên gia hạn sớm không mất gì. Giá là mức giá hiện tại trên trang, do chúng tôi tính. Không thể gia hạn số đã hết hạn: hãy mua số mới.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
packageenum body Không bắt buộcThời hạn gia hạn. Mặc định oneMonth. (duration được chấp nhận như một bí danh cũ.)
Một trongoneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header Bắt buộcMột UUID, mới cho mỗi lần gia hạn, dùng lại khi thử lại.
Đối tượng số đã cập nhật trong data; meta.charged, meta.currency, meta.wallet_balance_after.
Lỗi- 404Không phải số trong tài khoản của bạn.
- 422
insufficient_fundsVí không đủ tiền để gia hạn. - 422Đã hết hạn, đã hủy hoặc không thể gia hạn.
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
Bắt buộc có Idempotency-Key Hủy số để được hoàn tiền
Trả lại một số và hoàn toàn bộ giá vào ví của bạn. Chỉ được phép trong khoảng 15 đến 120 phút sau khi mua, khi số đang hoạt động và chưa nhận SMS nào. Ngoài các quy tắc đó, lệnh gọi bị từ chối với 422 và không có gì thay đổi; nếu quá sớm, details.seconds_until_open cho biết cần chờ bao lâu.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
Idempotency-Keystring header Bắt buộcMột UUID, dùng lại khi thử lại.
Đối tượng số (status cancelled) trong data; meta.refunded, meta.currency, meta.wallet_balance_after.
Lỗi- 404Không phải số trong tài khoản của bạn.
- 422Quá sớm (dưới 15 phút), quá muộn (trên 120 phút), đã nhận SMS hoặc không hoạt động.
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
Đọc SMS mà các số của bạn nhận được. Bạn nhận văn bản thô; việc trích xuất mã là do bạn.
Đối tượng tin nhắn SMS
Một SMS đã nhận, như được trả về bởi GET /numbers/{id}/sms. (GET /receive-sms dùng biến thể camelCase, được hiển thị ở endpoint đó.)
Trường-
idintegerId tin nhắn.
-
fromstringNgười gửi: một số điện thoại hoặc tên như WhatsApp.
-
bodystringToàn bộ văn bản tin nhắn.
-
received_atstringISO 8601, UTC.
Các bí danh đã ngừng hỗ trợ vẫn được gửi: sender (= from) và message (= body).
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
Lấy một số và SMS của số đó
Một số cùng mọi SMS nó đã nhận, mới nhất trước. Phù hợp nhất cho giao diện "xem chi tiết số này" và để thăm dò một số trong khi bạn chờ mã. Id không thuộc về bạn sẽ trả về 404.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
data.number (một đối tượng số) và data.messages (các đối tượng tin nhắn SMS); meta.count.
Lỗi- 404Không phải số trong tài khoản của bạn.
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
Nhận SMS theo số điện thoại
SMS phân trang theo con trỏ cho một số bạn sở hữu, xác định bằng số điện thoại thay vì id. Phù hợp nhất cho hộp thư có lưu lượng lớn. Số không thuộc về bạn sẽ trả về 403.
Tham số-
phoneNumberstring query Bắt buộcE.164 hoặc chỉ chữ số, ví dụ +14035551234. Mã hóa URL cho dấu +.
-
limitinteger query Không bắt buộcKích thước trang 1-100. Mặc định 50.
-
cursorstring query Không bắt buộcmeta.nextCursor từ trang trước.
-
data.messages[].idintegerId tin nhắn.
-
data.messages[].fromstringNgười gửi.
-
data.messages[].tostringSố của bạn.
-
data.messages[].messagestringToàn bộ văn bản.
-
data.messages[].receivedAtstringISO 8601.
-
meta.hasMore / nextCursorboolean / string | nullTruyền nextCursor làm cursor để lấy trang tiếp theo.
- 403Số này không thuộc tài khoản của bạn.
- 422phoneNumber bị thiếu hoặc không hợp lệ.
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"
}
}
Email riêng tư
Một hộp thư [email protected] miễn phí, chỉ nhận, cho mỗi số riêng. Mỗi số một địa chỉ.
Đối tượng email riêng
Hộp thư gắn với một số.
Trường-
addressstring | nullĐịa chỉ, hoặc null trước khi được nhận.
-
statusenumactive hoặc none.
-
unread_countintegerEmail chưa đọc.
-
created_atstring | nullThời điểm địa chỉ được nhận.
-
eligiblebooleanTrue khi số có thể nhận địa chỉ ngay bây giờ.
-
linked_numberstringSố điện thoại mà nó thuộc về.
-
domainstringprivnum.com
-
suggestionsstring[]Gợi ý tên khi đủ điều kiện.
{
"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
Lấy email riêng
Địa chỉ của một số, hoặc trước khi nhận địa chỉ, cho biết số có thể có địa chỉ hay không cùng một vài gợi ý tên.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
Một đối tượng email riêng trong data.
Lỗi- 404Không phải số trong tài khoản của bạn.
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
Kiểm tra tên
Kiểm tra trực tiếp rằng tên hợp lệ và còn trống trước khi bạn nhận.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
local_partstring query Bắt buộcPhần trước @: 3-64 chữ cái, chữ số, dấu chấm, dấu gạch ngang hoặc dấu gạch dưới.
-
availablebooleanTrue khi bạn có thể nhận nó.
-
reasonenum | nulltoo_short, too_long, invalid, reserved hoặc taken.
- 404Không phải số trong tài khoản của bạn.
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
Nhận địa chỉ
Cấp địa chỉ cho một số đang hoạt động. Miễn phí, mỗi số một địa chỉ, và địa chỉ đã nhận sẽ không bao giờ được giao cho người khác.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
local_partstring body Bắt buộcTên bạn đã kiểm tra.
Đối tượng email riêng trong data.
Lỗi- 404Không phải số của bạn, hoặc chưa có địa chỉ.
- 422Tên đã có người dùng hoặc không hợp lệ (details.reason), số đã có địa chỉ, hoặc số không hoạt động.
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
Liệt kê email
Tóm tắt email, mới nhất trước, phân trang theo trang và có số thư chưa đọc ở cấp cao nhất.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
pageinteger query Không bắt buộcSố trang. Mặc định 1.
-
per_pageinteger query Không bắt buộc1-100. Mặc định 25.
-
data[]arrayid, from_email, from_name, subject, preview, attachment_count, is_read, received_at.
-
metaobjectcurrent_page, per_page, total, last_page.
-
unread_countintegerỞ cấp cao nhất, cạnh data.
- 404Không phải số của bạn, hoặc chưa có địa chỉ.
- 404
private_email_closedSố đã bị hủy hoặc đã được hoàn tiền.
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
Đọc email
Toàn bộ email (HTML và văn bản) cùng danh sách tệp đính kèm. Đọc email sẽ đánh dấu là đã đọc.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
messageIdinteger path Bắt buộcId email từ danh sách hộp thư.
- 404Không phải số của bạn, hoặc chưa có địa chỉ.
- 404
private_email_closedSố đã bị hủy hoặc đã được hoàn tiền.
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ải tệp đính kèm
Tệp thô, với Content-Type và tên tệp riêng. index lấy từ attachments[] của email.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
messageIdinteger path Bắt buộcId email từ danh sách hộp thư.
-
indexinteger path Bắt buộcattachments[].index từ Đọc một email.
- 404Không phải số của bạn, hoặc chưa có địa chỉ.
- 404
private_email_closedSố đã bị hủy hoặc đã được hoàn tiền. - 404Không có tệp đính kèm ở vị trí đó.
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}
Xóa email
Xóa email và các tệp đính kèm của nó.
Tham số-
idinteger path Bắt buộcId số từ GET /numbers.
-
messageIdinteger path Bắt buộcId email từ danh sách hộp thư.
- 404Không phải số của bạn, hoặc chưa có địa chỉ.
- 404
private_email_closedSố đã bị hủy hoặc đã được hoàn tiền.
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
}
AI & MCP
Cho phép trợ lý AI sử dụng trực tiếp tài khoản của bạn, hoặc cung cấp cho agent lập trình mọi thứ cần thiết để xây dựng trên API.
Máy chủ MCP
Bên cạnh REST API, chúng tôi vận hành một máy chủ Model Context Protocol. Kết nối nó với Claude, ChatGPT hoặc trình soạn thảo của bạn và trợ lý có thể kiểm tra giá và số lượng còn, mua số và đọc SMS như các công cụ gốc, mà bạn không cần viết mã. Mới dùng MCP? Hãy bắt đầu với tổng quan về máy chủ MCP.
Endpointhttps://mcp.temp-number.com/mcp
Cách đăng nhập hoạt động
- Thêm URL vào ứng dụng AI của bạn. Ứng dụng sẽ chuyển bạn đến Temp Number để đăng nhập bằng tài khoản của chính bạn (OAuth 2.1 với PKCE) - không cần sao chép khóa.
- Trên màn hình cấp quyền, bạn chọn những gì trợ lý được phép làm. Việc đọc số dư, giá, các số của bạn và SMS của chúng luôn được bao gồm. Cho phép mua hàng - mua, gia hạn và hủy bằng ví của bạn - sẽ tắt trừ khi bạn đánh dấu chọn.
- Mọi kết nối đều được liệt kê tại Bảng điều khiển → Máy chủ MCP → Ứng dụng đã kết nối, nơi bạn có thể ngắt kết nối bất cứ lúc nào.
- Muốn dùng khóa (CI, script, agent không giao diện)? Tạo khóa MCP trên cùng trang đó và gửi nó dưới dạng
Authorization: Bearer <key>. Khóa MCP và khóa REST API không thể dùng thay thế cho nhau.
Công cụ
| Công cụ | Chức năng | Cần "Cho phép mua hàng" |
|---|---|---|
get-balance | Lấy số dư ví và loại tiền thanh toán của tài khoản đã xác thực. | Không |
get-pricing | Trả về bảng giá hiện hành cho tất cả quốc gia hoặc một mã quốc gia ISO. | Không |
get-inventory | Kiểm tra lượng hàng còn sẵn theo thời gian thực cho một quốc gia, thời hạn và loại số (tùy chọn). | Không |
purchase-number | Mua một số riêng cho tài khoản đã xác thực bằng tiền trong ví. | Có |
list-active-numbers | Trả về các số thuộc tài khoản đã xác thực, có thể lọc theo trạng thái. | Không |
check-sms | Lấy tin nhắn SMS của số đã mua theo ID thuộc tài khoản đã xác thực. | Không |
renew-number | Gia hạn số đã mua theo ID với gói thời hạn tùy chọn. | Có |
cancel-number | Hủy số đã mua theo ID và hoàn lại khoản tiền đủ điều kiện vào ví. | Có |
Kết nối công cụ AI của bạn
Chọn ứng dụng của bạn. Hầu hết kết nối chỉ với một cú nhấp: bạn đăng nhập vào Temp Number, đánh dấu những gì trợ lý được phép làm và nhấn Allow.
Claude - claude.ai, Desktop và di động
Không cần cài đặt gì. Hoạt động trên trình duyệt, ứng dụng máy tính và di động.
- Nhấn Add to Claude. Claude sẽ mở ra với Temp Number và URL đã được điền sẵn. Nhấn Add.
- Nhấn Connect, đăng nhập vào Temp Number, chọn có cho phép Claude mua hàng hay không, rồi nhấn Allow.
- Trong bất kỳ cuộc trò chuyện nào, mở menu + → Connectors và bật Temp Number. Thử hỏi: "Một số Mỹ giá bao nhiêu cho một tháng?"
Không thấy nút? Trong Claude, vào Customize → Connectors → Add custom connector và dán endpoint MCP. Các tổ chức có tùy chọn request header của Claude có thể gửi khóa MCP dưới dạng Authorization: Bearer <key> thay vì đăng nhập.
ChatGPT
Cần ChatGPT Business, Enterprise hoặc Edu trên web. Với gói Business, quản trị viên hoặc chủ sở hữu sẽ thêm nó.
- Sao chép URL máy chủ bên dưới, sau đó nhấn Mở ChatGPT để đến trang Plugins. ChatGPT không có liên kết tự động điền thông tin này cho bạn.
- Nhấn + → Add custom MCP server. Đặt tên là Temp Number và dán URL vào mục Connection.
- Đặt xác thực thành OAuth, chấp nhận cảnh báo rủi ro và nhấn Create as a plugin.
- Khi ChatGPT yêu cầu, hãy đăng nhập vào Temp Number, chọn có cho phép ChatGPT mua hàng hay không, rồi nhấn Allow.
- Trong một cuộc trò chuyện mới, gõ @ và chọn Temp Number. Thử hỏi: "Một số Mỹ giá bao nhiêu cho một tháng?"
https://mcp.temp-number.com/mcp
Claude Code
Thêm máy chủ một lần, sau đó đăng nhập ngay trong Claude Code.
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- Khởi động Claude Code và gõ
/mcp. - Chọn temp-number → Authenticate. Trình duyệt sẽ mở ra: đăng nhập và nhấn Allow.
Dùng khóa MCP thay thế (CI / không giao diện)
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
Thêm máy chủ, sau đó đăng nhập. Codex sẽ lưu phiên cho bạn.
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
Dùng khóa MCP thay thế (CI / không giao diện)
Trong ~/.codex/config.toml. Khóa được đọc từ biến môi trường, nên tệp này có thể chia sẻ an toàn.
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
Một cú nhấp, sau đó đăng nhập khi Cursor yêu cầu.
Hoặc thêm vào .cursor/mcp.json (hoặc ~/.cursor/mcp.json). Khi đó Cursor sẽ hiển thị Needs login cạnh máy chủ: nhấn vào đó, đăng nhập và nhấn Allow.
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Dùng khóa MCP thay thế
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
Một cú nhấp, sau đó đăng nhập vào lần đầu tiên một công cụ chạy.
Hoặc thêm vào .vscode/mcp.json - lưu ý khóa là servers, không phải mcpServers.
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
Dùng khóa MCP thay thế
VS Code hỏi khóa một lần và lưu nó trong kho bí mật của mình.
{
"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
}
]
}
Bất kỳ ứng dụng MCP nào khác
Windsurf, Zed, LibreChat, agent của riêng bạn…
- Thêm endpoint MCP như một máy chủ từ xa (streamable HTTP). Các ứng dụng hỗ trợ đăng nhập sẽ tự tìm thấy nó tại
https://mcp.temp-number.com/.well-known/oauth-protected-resourcevà mở màn hình cấp quyền của Temp Number. - Các ứng dụng không hỗ trợ đăng nhập có thể gửi khóa MCP dưới dạng
Authorization: Bearer <key>.
https://mcp.temp-number.com/mcp
llms.txt & prompt cho agent
Đang xây dựng cùng trợ lý lập trình AI? Hãy cung cấp cho nó ngữ cảnh bên dưới và nó có thể tích hợp API chính xác ngay lần đầu - bao gồm xác thực, idempotency và giới hạn tần suất.
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 là bản tóm tắt dạng văn bản thuần, luôn cập nhật, về mọi endpoint; đặc tả OpenAPI là hợp đồng có kiểu dữ liệu. Cả hai đều cập nhật cùng API.Tài nguyên
Những gì đã thay đổi và nơi nhận trợ giúp.
Nhật ký thay đổi
Chỉ có thay đổi bổ sung - không có gì trên /v1 bị loại bỏ.
-
NewMCP: đăng nhập bằng tài khoản Temp Number của bạn
"Add to Claude" bằng một cú nhấp, cùng ChatGPT, Claude Code, Codex, Cursor và VS Code mà không cần sao chép khóa. Bạn chọn trên màn hình đồng ý xem AI có được phép chi tiền hay không.
-
DocsNgôi nhà mới cho tài liệu
Hướng dẫn nhanh, tìm kiếm và mọi mẫu mã bằng cURL, Node.js, Python và PHP. Lỗi, giới hạn tần suất và hoàn tiền giờ khớp chính xác với API thực tế.
-
Newllms.txt cho toàn bộ trang web
Bản đồ dạng văn bản thuần về dịch vụ dành cho trợ lý AI, liên kết đến tài liệu tham chiếu API sẵn sàng cho agent.
-
NewKết nối công cụ AI của bạn
Thiết lập cho Claude Code, Codex, Cursor và VS Code, kèm liên kết cài đặt một cú nhấp cho Cursor và VS Code.
-
NewĐặc tả OpenAPI
Bản đặc tả máy đọc được có tại https://api.temp-number.com/api.json.
-
ImprovedCác đối tượng khớp với tài liệu tham chiếu
Số và SMS dùng ngày ISO 8601 và from/body. Lỗi mang mã máy đọc được (out_of_stock, insufficient_funds, invalid_duration). /inventory báo cáo mọi loại số khi bạn bỏ qua number_type. Tên trường cũ vẫn hoạt động dưới dạng bí danh đã ngừng hỗ trợ.
-
NewEndpoint email riêng
Nhận một hộp thư [email protected] miễn phí cho một số, đọc thư và tải tệp đính kèm qua API.
-
NewMáy chủ MCP
AI agent có thể xem giá, mua số và đọc SMS dưới dạng công cụ, bằng khóa MCP.
-
LaunchREST API công khai v1
Tài khoản, giá, kho số, vòng đời số và SMS, xác thực bằng Bearer token.
Hỗ trợ
Gặp khó khăn, hoặc thấy nội dung trong tài liệu này không khớp với cách API hoạt động? Liên hệ với chúng tôi - kèm endpoint, thời điểm gửi yêu cầu và nội dung phản hồi (tuyệt đối không gửi khóa API của bạn).
Sẵn sàng xây dựng?
Tạo khóa và thực hiện lệnh gọi đầu tiên trong chưa đầy một phút.