Introduction
The API is organized around REST. It uses standard HTTP response codes, authentication, and verbs. All requests must be made over HTTPS.
How to authenticate?
All protected routes require an API Token. You must send this token in the header of every request.
Authorization
Bearer YOUR_API_TOKEN
curl -X GET "https://directsms.net/api/v1/user" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
Get User Info
Returns profile information and account balance for the currently authenticated user.
Response Schema
Available account balance (Formatted with 2 decimals).
curl -X GET "https://directsms.net/api/v1/user" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": {
"id": 1,
"name": "John",
"balance": "150.00",
"email": "john@example.com"
}
}
List Categories
Retrieves all available categories (Countries) with their nested services.
curl -X GET "https://directsms.net/api/v1/categories" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": [
{
"id": 1,
"name": "United States",
"services": [...]
}
]
}
New Activation
Request a new virtual phone number for a specific service.
Request Body
The ID of the service you want to buy (e.g., WhatsApp, Google).
Specific operator if desired (any if null).
curl -X POST "https://directsms.net/api/v1/orders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_id": 125, "operator": "any"}'
{
"success": true,
"message": "Order created successfully",
"data": {
"id": 12345,
"service_id": 125,
"operator": "any",
"phone_number": "+1234567890",
"status": "PENDING",
"price": "0.50",
"created_at": "2024-01-15T10:30:00.000Z"
}
}
List Activations
Returns a paginated list of all activation orders for the authenticated user, sorted by most recent.
Security
Returns only orders belonging to the authenticated user. Cross-user access is blocked at the query level.
Query Parameters
Number of results per page. Default: 15. Maximum: 100.
Page number for pagination. Default: 1.
curl -X GET "https://directsms.net/api/v1/orders?per_page=15" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": [
{
"id": 12345,
"operator": "any",
"phone_number": "+1234567890",
"status": "OK",
"sms_code": "847291",
"price": "0.50",
"created_at": "2024-01-15T10:30:00.000Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 4,
"per_page": 15,
"total": 56
}
}
Get Activation
Retrieve the full details of a single activation order, including the received SMS code if available.
Security
Order ownership is verified server-side. Requesting an order that belongs to another user returns 404, not 403, to prevent enumeration attacks.
Path Parameters
The unique ID of the activation order.
Order Status Values
curl -X GET "https://directsms.net/api/v1/orders/12345" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": {
"id": 12345,
"operator": "any",
"phone_number": "+1234567890",
"status": "OK",
"sms_code": "847291",
"price": "0.50",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:32:00.000Z"
}
}
Check SMS Status
Polls the upstream provider for the latest status of an activation. Use this to check whether an SMS code has arrived. Poll at a reasonable interval β excessive polling is rate-limited.
Rate Limit
Poll no faster than every 3 seconds per order. Excessive requests will result in temporary throttling. The upstream provider may also impose its own limits.
Path Parameters
The activation order ID to poll.
curl -X POST "https://directsms.net/api/v1/orders/12345/update-status" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"message": "Order status updated",
"data": {
"id": 12345,
"status": "OK",
"sms_code": "847291",
"updated_at": "2024-01-15T10:32:00.000Z"
}
}
status field
Cancel Activation
Cancels an active activation order and refunds the balance to your account. Only orders in a cancellable state can be cancelled.
Security
Only the order owner can cancel. Attempting to cancel another user's order returns 404 to prevent enumeration.
Path Parameters
The activation order ID to cancel.
Cancellable Statuses
curl -X POST "https://directsms.net/api/v1/orders/12345/cancel" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"message": "Order cancelled and balance refunded",
"data": {
"id": 12345,
"status": "CANCELLED"
}
}
List Domains
Returns all active domains grouped by their category (Free, Premium, Edu, etc.)
curl -X GET "https://directsms.net/api/v1/temp-mail/domains" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"categories": {
"Free": [
{ "id": 1, "name": "cloudmail.life", "type": "free" }
],
"Premium": [
{ "id": 5, "name": "pro-inbox.com", "price": 0.5 }
]
}
}
Create Account
Creates a new temporary email account on the specified domain.
Request Body
The ID of the domain to create the email on.
curl -X POST "https://directsms.net/api/v1/temp-mail/generate" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain_id": 5}'
{
"success": true,
"data": {
"id": 125,
"email": "randomuser@pro-inbox.com",
"expires_at": "2024-12-25T23:59:59Z"
}
}
Get Messages
Retrieves all messages received by a specific temporary email account.
Path Parameters
The ID of the temporary email account.
curl -X GET "https://directsms.net/api/v1/temp-mail/messages/125" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": {
"email": "randomuser@pro-inbox.com",
"messages": [
{
"from": "noreply@example.com",
"subject": "Verification Code",
"body": "Your code is 123456",
"received_at": "2024-12-25T10:30:00Z"
}
]
}
}
Extend Duration
Extends the validity of an existing temporary email account.
Request Body
The ID of the temporary email account to extend.
curl -X POST "https://directsms.net/api/v1/temp-mail/extend" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"account_id": 125}'
{
"success": true,
"data": {
"new_expires_at": "2024-12-26T23:59:59Z"
}
}
Discard Account
Permanently deletes a temporary email account and all its messages.
Path Parameters
The ID of the temporary email account to delete.
curl -X DELETE "https://directsms.net/api/v1/temp-mail/discard/125" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true
}
Proxy Services
Lists all available proxy types (Residential, Mobile, Datacenter) and their configurations.
curl -X GET "https://directsms.net/api/v1/proxy/services" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": [
{
"id": "static-residential-ipv4",
"name": "Static Residential IPv4",
"plans": [...]
}
]
}
Setup Configuration
Returns available countries, regions, and periods for a specific service ID.
Request Body
The ID of the proxy service type.
curl -X POST "https://directsms.net/api/v1/proxy/setup" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_id": "static-residential-ipv4"}'
{
"success": true,
"data": {
"countries": ["US", "UK", "DE", "FR"],
"periods": ["1day", "7days", "30days"]
}
}
Purchase Proxy
Buys a proxy with the specified configuration. Balance will be deducted immediately.
curl -X POST "https://directsms.net/api/v1/proxy/purchase" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_id": "static-residential-ipv4", "country": "US", "period": "1month"}'
{
"success": true,
"data": {
"order_id": 552,
"proxies": [
{ "ip": "1.1.1.1", "port": "8080", "username": "user", ... }
]
}
}
Check Price
Calculates the final cost including profit margin for a specific proxy configuration.
Request Body
Send the same parameters you would use for purchase to get an exact quote.
curl -X POST "https://directsms.net/api/v1/proxy/price" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_id": "static-residential-ipv4", "country": "US", "period": "1month"}'
{
"success": true,
"data": {
"final_price": 1.83,
"currency": "USD"
}
}
Get Proxy Details
Retrieves connection details (Host, Port, Credentials) for an active proxy order.
curl -X GET "https://directsms.net/api/v1/proxy/order/552/proxies" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
[
{
"ip": "185.242.6.15",
"port": "3456",
"username": "proxy_user",
"password": "secure_pass",
"protocol": "http"
}
]
List Countries
Returns all countries where number rental is available. Use the country code returned here when listing services or creating a rental order.
Rental vs Activation
Number rental provides a persistent number for days or weeks, unlike one-time activations. Rental numbers can receive multiple SMS messages over their lifetime.
Response Fields
ISO 3166 country code β use as the country param in other rent endpoints
Human-readable country name
Flag emoji for display
curl -X GET "https://directsms.net/api/v1/rent/countries" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": [
{
"code": "US",
"name": "United States",
"flag": "πΊπΈ"
},
{
"code": "GB",
"name": "United Kingdom",
"flag": "π¬π§"
}
]
}
List Rental Services
Returns available rental services for a given country. Prices are per day β multiply by rental duration to estimate total cost.
Query Parameters
Numeric country ID from the List Countries endpoint.
ISO 4217 numeric currency code. Default: 840 (USD).
Response Fields
Service identifier β use as the service param when purchasing
Human-readable service name
Price per day in your account currency
7-day bundle price (may differ from 7Γ daily rate)
30-day bundle price
curl -X GET "https://directsms.net/api/v1/rent/services?country=1" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": {
"whatsapp": {
"key": "whatsapp",
"name": "WhatsApp",
"price_day": 0.12,
"price_week": 0.75,
"price_month": 2.80
},
"telegram": {
"key": "telegram",
"name": "Telegram",
"price_day": 0.10,
"price_week": 0.60,
"price_month": 2.20
}
}
}
Create Rental Order
Creates a number rental order. The cost is calculated server-side based on service pricing and deducted from your account balance. Discounts (if applicable) are applied automatically.
Security
Pricing is not accepted from the client β the server computes cost from the service's stored price data. All balance checks happen atomically to prevent double-spending.
Request Body
Numeric country ID from List Countries
Service key from List Services (e.g. whatsapp)
Rental duration in hours β min 4, max 168 (7 days)
Expected price (computed server-side, used for balance check)
Raw provider cost β omit to use price value
Enable call forwarding on the rented number
URL to receive SMS webhook notifications
Typical Flow
Call List Services first to get the price_day, then multiply by days (rent_time / 24) to compute the expected price before submitting.
curl -X POST "https://directsms.net/api/v1/rent/orders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"country": 1,
"service": "whatsapp",
"rent_time": 168,
"price": 0.75
}'
{
"success": true,
"message": "Kiralama sipariΕi oluΕturuldu",
"data": {
"id": 78901,
"phone_number": "+14155552671",
"country": 1,
"service": "whatsapp",
"status": "active",
"rent_time": 168,
"expires_at": "2024-01-22T10:30:00.000Z",
"created_at": "2024-01-15T10:30:00.000Z"
}
}
List Rental Orders
Returns all rental orders for the authenticated user, including active, expired, and cancelled rentals. Results are paginated and sorted by most recent.
Security
Rental orders are strictly scoped to the authenticated user. No cross-account access is possible regardless of the order ID.
Query Parameters
Results per page. Default: 15. Max: 100.
Page number. Default: 1.
Rental Status Values
curl -X GET "https://directsms.net/api/v1/rent/orders?per_page=10" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": [
{
"id": 78901,
"phone_number": "+14155552671",
"country": "US",
"service": "whatsapp",
"status": "ACTIVE",
"expires_at": "2024-01-22T10:30:00.000Z",
"created_at": "2024-01-15T10:30:00.000Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 2,
"per_page": 10,
"total": 18
}
}
Get Rental SMS Messages
Retrieves all SMS messages received by a rental number during its active period. Messages are returned in chronological order. Poll this endpoint to check for new incoming messages.
Polling Recommendation
Poll at most once every 5 seconds for active rentals. Messages are cached server-side so frequent polls don't slow down delivery.
Security
Messages are scoped to the order owner. Requesting messages from another user's rental returns 404, not 403, to prevent enumeration.
Path Parameters
The rental order ID.
curl -X GET "https://directsms.net/api/v1/rent/orders/78901/sms" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
{
"success": true,
"data": {
"sms_count": 2,
"sms_list": [
{
"text": "Your WhatsApp code: 291-847",
"code": "291847",
"sender": "WhatsApp",
"date": "2024-01-15 10:31:45"
},
{
"text": "Your WhatsApp code: 104-552",
"code": "104552",
"sender": "WhatsApp",
"date": "2024-01-16 08:22:10"
}
]
}
}