temphonenumberREST API v1.0

Carrier Gateway Engine • Operational • <150ms Latency

Carrier-grade SMS verification
built for scale & automation.

Direct programmatic provisioning of real non-VoIP physical SIM phone lines. Instant OTP webhook callbacks, multi-step session reuse, and high-throughput telephony routing for microservices, autonomous agents, and backend engineers.

GATEWAY BASE URLTLS 1.3 / HTTPS

https://api.temphonenumber.com

ACTIVE SDK / LANGUAGE

250req / min

<150mslatency

Non-VoIPSIM lines

99.4%success rate

Getting Started

•

Introduction

The temphonenumber API provides programmatic access to our carrier-grade physical SIM telephony network. All endpoints adhere to REST conventions, consume JSON request payloads, return standard JSON responses, and enforce standard OAuth 2.0 Bearer token authorization.

100% Real Physical SIMs

Real SIM cards connected to major tier-1 telecom carriers (AT&T, Verizon, T-Mobile, Vodafone). Works reliably on WhatsApp, OpenAI, Telegram, and Google without blocks.

Instant OTP Webhooks

Receive SMS payloads in real-time via signed HMAC-SHA256 HTTPS webhook callbacks or low-latency polling with sub-150ms processing speed.

Zero-Risk Auto Refund

If an SMS is not received within the activation window (or if you cancel/flag the number), credits are 100% refunded to your balance instantly.

Base URLs & Protocol Standards

Production Gatewayhttps://api.temphonenumber.com

Required HeadersContent-Type: application/json • Accept: application/json

POST/oauth/token

•

Authentication

To access authenticated endpoints, exchange your API Client ID and Client Secret for an OAuth2 Bearer Access Token. All subsequent requests require the Authorization: Bearer <token> header.

Header:Authorization: Bearer <token>

Scope: str:* ltr:* esim:* webhooks:*

Request Parameters

4 fields

client_idbodystring

Required

Your Developer API Client ID obtained from the Developer Settings dashboard.

Default: cli_live_9482019348

client_secretbodystring

Required

Your secret API key. Never expose this secret in client-side code or public repositories.

grant_typebodystring

Required

The OAuth 2.0 authorization grant type.

Default: client_credentials

Enums:

client_credentials

scopebodystring

Optional

Space-delimited list of permissions requested.

Default: *

Response Schema Attributes

4 attributes

access_tokenstring

e.g. tok_live_79a2f1c804b9e28d

Bearer authentication token to pass in headers.

token_typestring

e.g. Bearer

Always "Bearer".

expires_ininteger

e.g. 86400

Token lifetime in seconds (default: 86,400s / 24h).

scopestring

e.g. str:read str:write ltr:manage

Granted permission scopes.

HTTP Status Codes

200

OKCredentials valid. Token returned successfully.

400

Bad RequestMissing grant_type or malformed payload.

401

UnauthorizedInvalid client_id or client_secret.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "client_live_83920194",
    "client_secret": "sec_live_99482019348",
    "grant_type": "client_credentials"
  }'

RESPONSE200 OK

{
  "access_token": "tok_live_79a2f1c804b9e28d",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "str:read str:write ltr:manage esim:read webhook:manage"
}

Implementation Guide

•

Quick Start: 3-Step Verification Pipeline

Follow this complete programmatic workflow to order a real physical SIM line, trigger an SMS verification in your target app, and ingest the OTP code:

1GET /api/services

Query Services & Rates

Call GET /api/services to retrieve the service ID, current line availability, and cost per verification (e.g. WhatsApp, OpenAI, Telegram).

2POST /api/buyNumbers

Provision Physical SIM

Call POST /api/buyNumbers with the target websiteId to immediately allocate an active E.164 phone line.

3GET /api/getNumber/{id}

Receive OTP Code

Poll GET /api/getNumber/{id} every 3-5 seconds or register an instant HTTPS Webhook to receive the SMS OTP payload automatically.

Traffic & Quotas

•

Rate Limits & Throttling

Our gateway employs a sliding token-bucket algorithm to protect carrier interconnects and ensure maximum delivery throughput. Standard developer accounts are provisioned with 250 requests per minute. Enterprise tiers support up to 10,000 req/min.

Response Header	Type	Description	Example
X-RateLimit-Limit	integer	The maximum requests allowed per 60-second window.	250
X-RateLimit-Remaining	integer	Remaining quota of requests available in the current window.	248
X-RateLimit-Reset	unix timestamp	UTC timestamp when the rate limit window resets.	1723789400
Retry-After	seconds	Sent on HTTP 429. Number of seconds to pause before retrying.	3

Developer Tip: Webhooks vs. Polling

Instead of polling GET /api/getNumber/{id}, register a webhook using POST /api/webhook/set. Webhooks deliver OTPs within milliseconds of carrier receipt and consume zero rate limit quota.

Errors & Status Codes

•

Error Handling & Schemas

All error responses return standard HTTP status codes accompanied by a structured JSON payload containing a machine-readable error.code and human-readable message:

STANDARD ERROR RESPONSE FORMATHTTP 4xx / 5xx

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Your wallet balance is $0.25, but service WhatsApp requires $0.85.",
    "doc_url": "https://temphonenumber.com/en/developers/api#errors",
    "request_id": "req_8492019481"
  }
}

INSUFFICIENT_FUNDS (402)

Wallet balance is lower than the line purchase cost. Top up via billing portal.

NO_INVENTORY (404)

All physical SIM lines for this service/country are in use. Try another country or retry in 60s.

ORDER_EXPIRED (410)

The 20-minute activation window elapsed without SMS arrival. Full credit is refunded automatically.

UNAUTHORIZED (401)

Invalid or expired Bearer access token. Obtain a new token via POST /oauth/token.

RATE_LIMIT_EXCEEDED (429)

Exceeded the burst rate limit. Follow the Retry-After header duration.

INVALID_PARAMETERS (400)

Missing required JSON body parameters or invalid ISO country code.

GET/api/health

•

Gateway Health Check

Check the live operational status of the telephony gateway, active physical SIM bank nodes, and carrier interconnect latency.

Response Schema Attributes

4 attributes

statusstring

e.g. healthy

Overall health indicator ("healthy" | "degraded").

databasestring

e.g. connected

Database cluster connectivity status.

carriersstring

e.g. online

Tier-1 telephony gateway link state.

timestampstring (ISO 8601)

e.g. 2026-08-16T10:00:00.000Z

Server time of telemetry report.

HTTP Status Codes

200

OKAll systems, SIM nodes, and carrier links operational.

503

Service UnavailableGateway undergoing scheduled maintenance.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/health"

RESPONSE200 OK

{
  "status": "healthy",
  "database": "connected",
  "carriers": "online",
  "timestamp": "2026-08-16T10:00:00.000Z"
}

GET/api/version

•

Engine Version

Returns the active deployment version, supported protocol features, and build signature of the core telephony engine.

Response Schema Attributes

3 attributes

versionstring

e.g. 1.0.4

Semantic version of the active API release.

enginestring

e.g. telephony-v1-fast

Core routing engine build identifier.

regionstring

e.g. us-east-1

AWS / Cloudflare edge point-of-presence.

HTTP Status Codes

200

OKVersion metadata returned successfully.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/version"

RESPONSE200 OK

{
  "version": "1.0.4",
  "engine": "telephony-v1-fast",
  "region": "us-east-1"
}

GET/api/user/balance

•

Get Wallet Balance

Retrieve the real-time available credits, currency code, and auto-reload configuration for the authenticated account.

Header:Authorization: Bearer <token>

Scope: str:read

Response Schema Attributes

3 attributes

balancenumber (USD)

e.g. 148.50

Available wallet credits.

currencystring

e.g. USD

Billing currency (always "USD").

formattedstring

e.g. $148.50

Pre-formatted currency string.

HTTP Status Codes

200

OKWallet balance retrieved successfully.

401

UnauthorizedMissing or invalid Bearer token.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/user/balance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "balance": 148.5,
  "currency": "USD",
  "formatted": "$148.50"
}

GET/api/user/profile

•

Get Account Profile

Retrieve developer account tier, verified email, registration dates, rate limit ceilings, and active webhook routing state.

Header:Authorization: Bearer <token>

Scope: account:read

Response Schema Attributes

6 attributes

userIdstring

e.g. usr_pva_8920194

Unique customer identifier.

emailstring

e.g. [email protected]

Developer account primary email address.

tierstring

e.g. SCALE_PRO

Active plan tier ("STARTER" | "SCALE_PRO" | "ENTERPRISE").

rateLimitstring

e.g. 2,000 req/min

Provisioned requests per minute.

webhookStatusstring

e.g. ACTIVE

Real-time webhook listener state ("ACTIVE" | "NONE").

createdAtstring (ISO 8601)

e.g. 2025-01-12T08:00:00Z

Account creation timestamp.

HTTP Status Codes

200

OKProfile details returned.

401

UnauthorizedMissing or expired Bearer token.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/user/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "userId": "usr_pva_8920194",
  "email": "[email protected]",
  "tier": "SCALE_PRO",
  "rateLimit": "2,000 req/min",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-01-12T08:00:00Z"
}

GET/api/services

•

Get All Services

Retrieve the complete directory of supported verification services, per-verification pricing in USD, and real-time available SIM inventory.

Request Parameters

3 fields

limitqueryinteger

Optional

Number of services to return (max 200).

Default: 50

countryquerystring

Optional

Filter services by ISO 3166-1 alpha-2 country code.

Default: US

Enums:

USGBCADEFRNL

categoryquerystring

Optional

Filter by category.

Enums:

messagingsocialbankingaigaming

Response Schema Attributes

5 attributes

totalinteger

e.g. 148

Total number of services matching query.

services[].idstring

e.g. 69a13a4ef133cd20b4a7c082

Unique service identifier (pass to /api/buyNumbers).

services[].namestring

e.g. WhatsApp

Human-readable service title.

services[].pricenumber

e.g. 0.85

Cost in USD per successful OTP verification.

services[].availableinteger

e.g. 420

Real-time count of ready physical SIM lines.

HTTP Status Codes

200

OKServices directory returned.

400

Bad RequestInvalid country code format.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/services?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "total": 148,
  "services": [
    {
      "id": "69a13a4ef133cd20b4a7c082",
      "name": "WhatsApp",
      "price": 0.85,
      "available": 420,
      "country": "US"
    },
    {
      "id": "69a13a4ef133cd20b4a7c083",
      "name": "OpenAI / ChatGPT",
      "price": 0.75,
      "available": 310,
      "country": "US"
    },
    {
      "id": "69a13a4ef133cd20b4a7c084",
      "name": "Telegram",
      "price": 0.65,
      "available": 890,
      "country": "US"
    }
  ]
}

GET/api/services/{id}

•

Get Service by ID

Retrieve live inventory, pricing, carrier reliability score, and real-time OTP delivery rates for a specific service ID.

Request Parameters

1 fields

idpathstring

Required

Unique service identifier (e.g. "69a13a4ef133cd20b4a7c082" or "whatsapp").

Default: 69a13a4ef133cd20b4a7c082

Response Schema Attributes

5 attributes

idstring

e.g. 69a13a4ef133cd20b4a7c082

Service UUID.

namestring

e.g. WhatsApp

Service brand name.

pricenumber

e.g. 0.85

Price in USD per activation.

successRatestring

e.g. 99.4%

Historical 24-hour OTP delivery success percentage.

supportedCountriesstring[]

e.g. ["US", "GB", "CA", "DE"]

Array of ISO country codes with active inventory.

HTTP Status Codes

200

OKService details returned.

404

Not FoundService ID does not exist.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/services/69a13a4ef133cd20b4a7c082" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "id": "69a13a4ef133cd20b4a7c082",
  "name": "WhatsApp",
  "category": "Messaging",
  "price": 0.85,
  "successRate": "99.4%",
  "availableLines": 420,
  "supportedCountries": [
    "US",
    "GB",
    "CA",
    "DE",
    "FR",
    "NL"
  ]
}

GET/api/countries

•

List Countries

Retrieve all supported telephony regions, ISO-3166 country codes, international dial prefixes, and physical SIM inventory metrics.

Request Parameters

1 fields

service_idquerystring

Optional

Filter countries that currently possess stock for a specific service.

Response Schema Attributes

5 attributes

totalCountriesinteger

e.g. 195

Total supported country count (190+).

countries[].isostring (ISO 2)

e.g. US

2-letter country code.

countries[].namestring

e.g. United States

Full country name.

countries[].dialCodestring

e.g. +1

E.164 country dial prefix.

countries[].nonVoipboolean

e.g. true

Guarantees 100% physical SIM line.

HTTP Status Codes

200

OKCountries list returned successfully.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/countries"

RESPONSE200 OK

{
  "totalCountries": 195,
  "countries": [
    {
      "iso": "US",
      "name": "United States",
      "dialCode": "+1",
      "flag": "🇺🇸",
      "nonVoip": true
    },
    {
      "iso": "GB",
      "name": "United Kingdom",
      "dialCode": "+44",
      "flag": "🇬🇧",
      "nonVoip": true
    },
    {
      "iso": "CA",
      "name": "Canada",
      "dialCode": "+1",
      "flag": "🇨🇦",
      "nonVoip": true
    },
    {
      "iso": "DE",
      "name": "Germany",
      "dialCode": "+49",
      "flag": "🇩🇪",
      "nonVoip": true
    }
  ]
}

POST/api/buyNumbers

•

Purchase Number (STR)

Allocate a dedicated non-VoIP physical SIM phone line for short-term single or multi-SMS verification.

Header:Authorization: Bearer <token>

Scope: str:write

Request Parameters

4 fields

websiteIdbodystring

Required

Target service identifier obtained from /api/services.

Default: 69a13a4ef133cd20b4a7c082

quantitybodyinteger

Optional

Number of lines to provision simultaneously (1 - 50).

Default: 1

countrybodystring

Optional

2-letter ISO country code for the phone line.

Default: US

Enums:

USGBCADEFRNL

webhook_urlbodystring (URL)

Optional

Dynamic HTTPS callback endpoint for instant SMS OTP delivery.

Response Schema Attributes

5 attributes

orderIdstring

e.g. ord_69d4b8946fdb87c1f163e1c9

Unique order identifier to track OTP or cancel.

statusstring

e.g. PENDING

Initial order state ("PENDING" | "ACTIVE").

phoneNumberstring (E.164)

e.g. +14155552671

Allocated physical SIM phone number.

costnumber (USD)

e.g. 0.85

Deducted credit amount in USD.

expiresAtinteger (unix)

e.g. 1723790600

Timestamp when 20-min activation window closes.

HTTP Status Codes

200

OKPhysical line allocated and activated successfully.

400

Bad RequestMissing websiteId or invalid country code.

401

UnauthorizedInvalid or missing Bearer token.

402

Payment RequiredInsufficient balance to purchase number.

404

Not FoundNo physical SIM lines currently available for this service.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/buyNumbers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": "69a13a4ef133cd20b4a7c082",
    "quantity": 1,
    "webhook_url": "https://my-app.com/webhooks/sms"
  }'

RESPONSE200 OK

{
  "orderId": "ord_69d4b8946fdb87c1f163e1c9",
  "status": "PENDING",
  "phoneNumber": "+14155552671",
  "expiresAt": 1723790600,
  "cost": 0.85
}

GET/api/getNumber/{id}

•

Get Active Order & SMS OTP

Poll the status of an active number order and retrieve incoming SMS text and extracted OTP code.

Header:Authorization: Bearer <token>

Scope: str:read

Request Parameters

1 fields

idpathstring

Required

Order identifier returned from /api/buyNumbers.

Default: ord_69d4b8946fdb87c1f163e1c9

Response Schema Attributes

6 attributes

orderIdstring

e.g. ord_69d4b8946fdb87c1f163e1c9

Order identifier.

statusstring

e.g. COMPLETED

"PENDING" | "COMPLETED" | "EXPIRED" | "FLAGGED".

phoneNumberstring (E.164)

e.g. +14155552671

Active phone number.

smsstring

e.g. Your WhatsApp code is: 849-201

Complete received SMS text payload.

codestring

e.g. 849201

Parsed numeric or alphanumeric verification code.

receivedAtstring (ISO 8601)

e.g. 2026-08-16T10:14:22Z

UTC timestamp of SMS delivery.

HTTP Status Codes

200

OKOrder details and SMS message payload returned.

401

UnauthorizedMissing or expired Bearer token.

404

Not FoundOrder ID not found.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/getNumber/ord_69d4b8946fdb87c1f163e1c9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "orderId": "ord_69d4b8946fdb87c1f163e1c9",
  "status": "COMPLETED",
  "phoneNumber": "+14155552671",
  "sms": "Your WhatsApp code is: 849-201",
  "code": "849201",
  "receivedAt": "2026-08-16T10:14:22Z"
}

POST/api/flagNumber/{id}

•

Flag Number (Refund Credit)

Cancel an unresponsive number and instantly release the line back to carrier pool with full credit refund.

Header:Authorization: Bearer <token>

Scope: str:write

Request Parameters

1 fields

idpathstring

Required

Order ID to cancel and refund.

Default: ord_69d4b8946fdb87c1f163e1c9

Response Schema Attributes

4 attributes

orderIdstring

e.g. ord_69d4b8946fdb87c1f163e1c9

Cancelled order ID.

statusstring

e.g. FLAGGED_REFUNDED

Updated state: "FLAGGED_REFUNDED".

refundedAmountnumber (USD)

e.g. 0.85

Exact balance credited back to wallet.

refundedAtstring (ISO 8601)

e.g. 2026-08-16T10:14:22.000Z

UTC timestamp of refund event.

HTTP Status Codes

200

OKLine cancelled and balance refunded immediately.

400

Bad RequestNumber has already received an SMS and cannot be flagged.

404

Not FoundOrder ID not found.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/flagNumber/ord_69d4b8946fdb87c1f163e1c9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "orderId": "ord_69d4b8946fdb87c1f163e1c9",
  "status": "FLAGGED_REFUNDED",
  "refundedAmount": 0.85,
  "refundedAt": "2026-08-16T10:14:22.000Z"
}

POST/api/reuseNumber/{id}

•

Reuse Phone Number

Re-activate a previously used physical SIM number for 2FA re-verification or subsequent SMS messages.

Header:Authorization: Bearer <token>

Scope: str:write

Request Parameters

1 fields

idpathstring

Required

Original order ID to reactivate.

Default: ord_69d4b8946fdb87c1f163e1c9

Response Schema Attributes

4 attributes

orderIdstring

e.g. ord_69d4b8946fdb87c1f163e1c9

New order identifier.

reusedboolean

e.g. true

Confirms line reactivation.

phoneNumberstring (E.164)

e.g. +14155552671

Same dedicated phone number.

expiresAtinteger (unix)

e.g. 1723791200

New expiration timestamp.

HTTP Status Codes

200

OKPhone number re-activated.

404

Not FoundNumber is no longer available in the carrier pool.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/reuseNumber/ord_69d4b8946fdb87c1f163e1c9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "orderId": "ord_69d4b8946fdb87c1f163e1c9",
  "reused": true,
  "status": "ACTIVE",
  "phoneNumber": "+14155552671",
  "expiresAt": 1723791200
}

GET/api/sms/{id}

•

Get SMS Messages

Poll or fetch message history and delivery logs for a given rental transaction or line ID.

Header:Authorization: Bearer <token>

Scope: str:read

Request Parameters

1 fields

idpathstring

Required

Order ID to query.

Default: ord_69d4b8946fdb87c1f163e1c9

Response Schema Attributes

4 attributes

orderIdstring

e.g. ord_69d4b8946fdb87c1f163e1c9

Order identifier.

messages[].senderstring

e.g. WhatsApp

Service or sender identity.

messages[].bodystring

e.g. Your WhatsApp verification code is: 849-201

Full text body.

messages[].codestring

e.g. 849201

Parsed verification code.

HTTP Status Codes

200

OKMessages list returned.

404

Not FoundOrder ID not found.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/sms/ord_69d4b8946fdb87c1f163e1c9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "orderId": "ord_69d4b8946fdb87c1f163e1c9",
  "messages": [
    {
      "sender": "WhatsApp",
      "body": "Your WhatsApp verification code is: 849-201",
      "code": "849201",
      "receivedAt": "2026-08-16T10:14:22Z"
    }
  ]
}

POST/api/ltr/rent

•

Rent Long-Term Number (LTR)

Reserve a persistent dedicated physical SIM number for 7, 30, or 90 days with unlimited incoming SMS reception.

Header:Authorization: Bearer <token>

Scope: ltr:manage

Request Parameters

4 fields

serviceIdbodystring

Required

Service identifier or "all" for multi-service inbox.

Default: all

durationDaysbodyinteger

Required

Lease period in days (7, 30, 90, 180, 365).

Default: 30

Enums:

73090180365

countrybodystring

Optional

ISO country code.

Default: US

autoRenewbodyboolean

Optional

Auto-renew line from wallet balance before expiration.

Default: false

Response Schema Attributes

5 attributes

rentalIdstring

e.g. ltr_9481948201

Dedicated subscription UUID.

statusstring

e.g. ACTIVE

Subscription state ("ACTIVE").

phoneNumberstring (E.164)

e.g. +14155558912

Dedicated physical SIM line.

expiresAtstring (ISO 8601)

e.g. 2026-09-15T10:00:00Z

UTC subscription expiry timestamp.

pricenumber (USD)

e.g. 18.50

Billed monthly rate.

HTTP Status Codes

200

OKLong term number reserved and dedicated to account.

402

Payment RequiredInsufficient balance to cover rental.

404

Not FoundNo physical SIM lines available in specified region.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/ltr/rent" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "69a13a4ef133cd20b4a7c082",
    "durationDays": 30,
    "country": "US"
  }'

RESPONSE200 OK

{
  "rentalId": "ltr_9481948201",
  "status": "ACTIVE",
  "phoneNumber": "+14155558912",
  "country": "US",
  "service": "WhatsApp + Telegram + Any",
  "startsAt": "2026-08-16T10:00:00Z",
  "expiresAt": "2026-09-15T10:00:00Z",
  "autoRenew": false,
  "price": 18.5
}

PUT/api/ltr/renew/{id}

•

Renew LTR Line

Extend the lease duration of an existing long-term dedicated number before expiry to preserve the phone line.

Header:Authorization: Bearer <token>

Scope: ltr:manage

Request Parameters

2 fields

idpathstring

Required

Long-term rental ID to renew.

Default: ltr_9481948201

extendDaysbodyinteger

Required

Number of additional days to extend lease.

Default: 30

Enums:

73090180365

Response Schema Attributes

4 attributes

rentalIdstring

e.g. ltr_9481948201

Rental UUID.

statusstring

e.g. RENEWED

"RENEWED".

newExpiresAtstring (ISO 8601)

e.g. 2026-10-15T10:00:00Z

Extended expiry UTC timestamp.

chargedAmountnumber (USD)

e.g. 18.50

Renewal price charged to wallet.

HTTP Status Codes

200

OKLine renewed successfully.

402

Payment RequiredInsufficient balance to cover renewal.

404

Not FoundRental ID not found or already decommissioned.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X PUT "https://api.temphonenumber.com/api/ltr/renew/ltr_9481948201" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "extendDays": 30 }'

RESPONSE200 OK

{
  "rentalId": "ltr_9481948201",
  "status": "RENEWED",
  "phoneNumber": "+14155558912",
  "newExpiresAt": "2026-10-15T10:00:00Z",
  "chargedAmount": 18.5
}

GET/api/ltr/rentals

•

Get Active LTR Rentals

Retrieve all active and expiring long-term physical SIM number subscriptions associated with your account.

Header:Authorization: Bearer <token>

Scope: ltr:manage

Response Schema Attributes

5 attributes

totalinteger

e.g. 2

Active rentals count.

rentals[].idstring

e.g. ltr_9481948201

Subscription UUID.

rentals[].phoneNumberstring (E.164)

e.g. +14155558912

Assigned telephone number.

rentals[].servicestring

e.g. All Services

Configured service routing scope.

rentals[].expiresAtstring (ISO 8601)

e.g. 2026-09-15T10:00:00Z

Expiry UTC timestamp.

HTTP Status Codes

200

OKActive rentals list returned.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/ltr/rentals" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "total": 2,
  "rentals": [
    {
      "id": "ltr_9481948201",
      "phoneNumber": "+14155558912",
      "service": "All Services",
      "expiresAt": "2026-09-15T10:00:00Z",
      "status": "ACTIVE"
    },
    {
      "id": "ltr_9481948202",
      "phoneNumber": "+447700900123",
      "service": "WhatsApp",
      "expiresAt": "2026-09-20T10:00:00Z",
      "status": "ACTIVE"
    }
  ]
}

GET/api/ltr/sms/{id}

•

Get LTR SMS Inbox

Retrieve all historical and real-time incoming SMS text payloads received by a persistent long-term phone number.

Header:Authorization: Bearer <token>

Scope: ltr:manage

Request Parameters

1 fields

idpathstring

Required

Long-term rental ID.

Default: ltr_9481948201

Response Schema Attributes

4 attributes

rentalIdstring

e.g. ltr_9481948201

Rental UUID.

messages[].fromstring

e.g. +18005550199

Sender telephone or shortcode.

messages[].textstring

e.g. Security code: 591042

Full SMS body.

messages[].codestring

e.g. 591042

Extracted verification PIN.

HTTP Status Codes

200

OKInbox messages returned.

404

Not FoundRental ID not found.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/ltr/sms/ltr_9481948201" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "rentalId": "ltr_9481948201",
  "messages": [
    {
      "id": "msg_01",
      "from": "+18005550199",
      "text": "Security code: 591042",
      "code": "591042",
      "receivedAt": "2026-08-16T11:20:00Z"
    },
    {
      "id": "msg_02",
      "from": "+18005550199",
      "text": "Password reset PIN is 301984",
      "code": "301984",
      "receivedAt": "2026-08-16T12:05:00Z"
    }
  ]
}

POST/api/webhook/set

•

Set Webhook Endpoint

Header:Authorization: Bearer <token>

Scope: webhook:manage

Request Parameters

2 fields

urlbodystring (HTTPS URL)

Required

Publicly reachable HTTPS endpoint on your server to receive JSON event posts.

Default: https://api.myapp.com/webhooks/temphonenumber

eventsbodystring[]

Optional

Array of event types to subscribe to.

Default: ["sms.received", "order.completed"]

Enums:

sms.receivedorder.completedorder.refundedorder.expired

Response Schema Attributes

4 attributes

statusstring

e.g. WEBHOOK_CONFIGURED

"WEBHOOK_CONFIGURED".

urlstring

e.g. https://api.myapp.com/webhooks/temphonenumber

Registered endpoint URL.

secretstring

e.g. whsec_9482019348123984

HMAC-SHA256 signing secret for payload verification.

eventsstring[]

e.g. ["sms.received", "order.completed"]

Subscribed event topics.

HTTP Status Codes

200

OKWebhook registered and signing secret returned.

400

Bad RequestInvalid HTTPS URL format.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/webhook/set" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.myapp.com/webhooks/temphonenumber",
    "events": ["sms.received", "order.completed"]
  }'

RESPONSE200 OK

{
  "status": "WEBHOOK_CONFIGURED",
  "url": "https://api.myapp.com/webhooks/temphonenumber",
  "secret": "whsec_9482019348123984",
  "events": [
    "sms.received",
    "order.completed"
  ]
}

GET/api/webhook/get

•

Get Webhook Configuration

Retrieve the currently active webhook endpoint URL, subscribed event topics, and signature verification client ID.

Header:Authorization: Bearer <token>

Scope: webhook:manage

Response Schema Attributes

4 attributes

urlstring

e.g. https://api.myapp.com/webhooks/temphonenumber

Active destination URL.

statusstring

e.g. ACTIVE

Listener state ("ACTIVE").

eventsstring[]

e.g. ["sms.received", "order.completed"]

Subscribed event topics.

lastDeliveryStatusstring

e.g. 200 OK

HTTP status of the most recent webhook delivery attempt.

HTTP Status Codes

200

OKWebhook configuration returned.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X GET "https://api.temphonenumber.com/api/webhook/get" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "url": "https://api.myapp.com/webhooks/temphonenumber",
  "status": "ACTIVE",
  "events": [
    "sms.received",
    "order.completed",
    "order.refunded"
  ],
  "lastDeliveryStatus": "200 OK",
  "lastDeliveryAt": "2026-08-16T12:00:00Z"
}

DELETE/api/webhook/delete

•

Delete Webhook

Deactivate and delete the configured webhook callback destination from your account.

Header:Authorization: Bearer <token>

Scope: webhook:manage

Response Schema Attributes

2 attributes

statusstring

e.g. WEBHOOK_DELETED

"WEBHOOK_DELETED".

messagestring

e.g. Webhook endpoint removed successfully

Confirmation message.

HTTP Status Codes

200

OKWebhook removed.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X DELETE "https://api.temphonenumber.com/api/webhook/delete" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "status": "WEBHOOK_DELETED",
  "message": "Webhook endpoint removed successfully"
}

POST/api/webhook/test

•

Send Test Webhook Event

Trigger a sample mock verification event payload to your configured URL to verify HMAC signature verification logic.

Header:Authorization: Bearer <token>

Scope: webhook:manage

Response Schema Attributes

4 attributes

statusstring

e.g. TEST_EVENT_SENT

"TEST_EVENT_SENT".

deliveredboolean

e.g. true

True if server acknowledged with 2xx.

responseStatusCodeinteger

e.g. 200

HTTP status code received from your server.

latencyMsinteger

e.g. 142

Round-trip delivery duration in milliseconds.

HTTP Status Codes

200

OKTest ping dispatched to callback URL.

502

Bad GatewayDestination server returned non-2xx status code.

Was this section helpful?

AUTHENTICATED REQUEST

curl -X POST "https://api.temphonenumber.com/api/webhook/test" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE200 OK

{
  "status": "TEST_EVENT_SENT",
  "delivered": true,
  "responseStatusCode": 200,
  "latencyMs": 142,
  "samplePayload": {
    "event": "sms.received",
    "phoneNumber": "+14155552671",
    "sms": "Your verification code is 849201",
    "code": "849201"
  }
}

Security & Webhooks

•

Verify Webhook Signatures

temphonenumber signs all outbound webhook event payloads with an HMAC-SHA256 signature using your account's webhook secret. Verify this signature to prevent replay attacks and ensure requests originate strictly from temphonenumber servers.

Headers Dispatched With Each Event

Signature HeaderX-temphonenumber-Signature

Timestamp HeaderX-temphonenumber-Timestamp

NODE.js / EXPRESS SIGNATURE VERIFICATIONcrypto.timingSafeEqual

import crypto from 'crypto';
import express from 'express';

const app = express();
// Ensure you capture raw body buffer for signature calculation
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

app.post('/webhooks/temphonenumber', (req, res) => {
  const signature = req.headers['x-temphonenumber-signature'];
  const timestamp = req.headers['x-temphonenumber-timestamp'];
  const webhookSecret = process.env.TEMP_PHONE_WEBHOOK_SECRET;

  // 1. Concatenate timestamp and raw body
  const signedPayload = `${timestamp}.${req.rawBody}`;

  // 2. Compute expected HMAC-SHA256 signature
  const expectedSig = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload)
    .digest('hex');

  // 3. Prevent timing attacks via constant-time comparison
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSig, 'hex')
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process verified event payload
  const event = req.body;
  if (event.event === 'sms.received') {
    console.log('OTP received:', event.code, 'for line:', event.phoneNumber);
  }

  res.status(200).json({ received: true });
});

SDK & Client Libraries

•

Node.js / TypeScript SDK

Official TypeScript and Node.js client featuring built-in exponential retry logic, static typing for all endpoints, and automatic OAuth2 token management:

📦 npm install @temphonenumber/sdkv1.4.2 • TypeScript Ready

import { temphonenumber } from '@temphonenumber/sdk';

const client = new temphonenumber({
  clientId: process.env.TEMP_PHONE_CLIENT_ID!,
  clientSecret: process.env.TEMP_PHONE_CLIENT_SECRET!,
});

// 1. Purchase a physical SIM number
const order = await client.str.purchase({
  service: 'whatsapp',
  country: 'US',
});
console.log('Allocated line:', order.phoneNumber);

// 2. Wait for incoming SMS OTP code
const message = await client.str.waitForCode(order.id, { timeoutMs: 120_000 });
console.log('Verification code received:', message.code);

SDK & Client Libraries

•

Python SDK

Official Python package with complete support for async/await (asyncio), synchronous requests, and Pydantic response validation:

🐍 pip install temphonenumberv1.2.0 • Python 3.9+

from temphonenumber import temphonenumberClient

client = temphonenumberClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Purchase physical line for OpenAI / ChatGPT
order = client.str.purchase(service="openai", country="US")
print(f"Purchased number: {order.phone_number}")

# Wait for SMS code with built-in poll helper
sms = client.str.wait_for_sms(order.order_id, timeout_seconds=120)
print(f"SMS Received: {sms.code}")

Go SDK

High-concurrency Go module with native context cancellation, connection pooling, and zero external dependencies:

🐹 go get github.com/temphonenumber/go-sdkv1.1.0 • Go 1.21+

package main

import (
	"context"
	"fmt"
	"github.com/temphonenumber/go-sdk"
)

func main() {
	client := temphonenumber.NewClient("client_id", "client_secret")
	ctx := context.Background()

	order, err := client.STR.Purchase(ctx, &temphonenumber.PurchaseParams{
		WebsiteID: "telegram",
		Quantity:  1,
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Line: %s\n", order.PhoneNumber)
}

PHP SDK

Composer-compatible PHP client supporting Laravel Service Providers, Symfony Bundles, and standalone PSR-18 HTTP clients:

🐘 composer require temphonenumber/php-sdkv1.0.4 • PHP 8.1+

use temphonenumber\Client;

$client = new Client('client_id', 'client_secret');

$order = $client->str()->purchase([
    'websiteId' => 'whatsapp',
    'country' => 'US',
]);

echo "Assigned number: " . $order->phoneNumber;

cURL & Raw HTTP

Execute direct cURL commands in bash scripts, CI/CD pipelines, Docker containers, and microservices:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.temphonenumber.com/api/buyNumbers -d '{"websiteId":"whatsapp"}'

Carrier-grade SMS verification built for scale & automation.

Introduction

100% Real Physical SIMs

Instant OTP Webhooks

Zero-Risk Auto Refund

Base URLs & Protocol Standards

Authentication

Request Parameters

Response Schema Attributes

HTTP Status Codes

Quick Start: 3-Step Verification Pipeline

Query Services & Rates

Provision Physical SIM

Receive OTP Code

Rate Limits & Throttling

Error Handling & Schemas

Gateway Health Check

Response Schema Attributes

HTTP Status Codes

Engine Version

Response Schema Attributes

HTTP Status Codes

Get Wallet Balance

Response Schema Attributes

HTTP Status Codes

Get Account Profile

Response Schema Attributes

HTTP Status Codes

Get All Services

Request Parameters

Response Schema Attributes

HTTP Status Codes

Get Service by ID

Request Parameters

Response Schema Attributes

HTTP Status Codes

List Countries

Request Parameters

Response Schema Attributes

HTTP Status Codes

Purchase Number (STR)

Request Parameters

Response Schema Attributes

HTTP Status Codes

Get Active Order & SMS OTP

Request Parameters

Response Schema Attributes

HTTP Status Codes

Flag Number (Refund Credit)

Request Parameters

Response Schema Attributes

HTTP Status Codes

Reuse Phone Number

Request Parameters

Response Schema Attributes

HTTP Status Codes

Get SMS Messages

Request Parameters

Response Schema Attributes

HTTP Status Codes

Rent Long-Term Number (LTR)

Request Parameters

Response Schema Attributes

HTTP Status Codes

Renew LTR Line

Request Parameters

Response Schema Attributes

HTTP Status Codes

Get Active LTR Rentals

Response Schema Attributes

HTTP Status Codes

Get LTR SMS Inbox

Request Parameters

Response Schema Attributes

HTTP Status Codes

Set Webhook Endpoint

Request Parameters

Response Schema Attributes

HTTP Status Codes

Get Webhook Configuration

Carrier-grade SMS verification
built for scale & automation.