API Documentation

Authentication

All API requests must be authenticated. Include your API key in the request headers as `Auth: YOUR_API_KEY`. You can find your API key in your user profile page.

Example Header

"Auth": "sk_your_very_secret_api_key"

POST /api/v1/rent-a-number

This endpoint allows you to request a new phone number for a specific service. You need to provide the service code you want to verify. The code can be viewed on the "Services" in our platform. (2 Request per second)

Request Body Parameters

{
    "service": "whatsapp", // REQUIRED: Service API name
    "max_price": 1.00, // OPTIONAL: Maximum price willing to pay
    "carrier": "at&t", // OPTIONAL: Preferred carrier
    "keep_carrier": true, // OPTIONAL: Force carrier match (boolean)
    "lock_area_code": true, // OPTIONAL: Strict area code matching (boolean)
    "area_codes": "123,456,789" // OPTIONAL: Comma-separated area codes
}

Pricing Notes

// Base price multipliers:
// - Carrier match only: +20% (price × 1.2)
// - Area code match only: +20% (price × 1.2)
// - Both carrier and area code match: +40% (price × 1.4)

Example cURL Request

curl -X POST https://getatext.com/api/v1/rent-a-number \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "service": "whatsapp",
    "max_price": 1.00,
    "carrier": "at&t",
    "keep_carrier": true,
    "area_codes": "212,646"
}'

Successful Response (201 CREATED)

{
    "id": 12345,
    "status": "success",
    "message": "Number rented successfully.",
    "errors": null,
    "end_time": "2025-07-06 15:43:37",
    "number": "1234567890",
    "service_name": "Whatsapp",
    "price": "0.55",
    "new_balance": "113.32"
}

Error Responses

// 503 Service Unavailable - Maintenance Mode
{
    "errors": "Service is under maintenance"
}

// 403 Forbidden - Missing Authentication
{
    "errors": "Auth is not presented on the request"
}

// 403 Forbidden - Invalid API Key or User Restricted
{
    "errors": "Wrong Api Key or User is restricted"
}

// 400 Bad Request - Missing Service Parameter
{
    "errors": "Service is not presented on the request"
}

// 400 Bad Request - Wrong Carrier
{
    "errors": "Wrong Carrier"
}

// 404 Not Found - Service Not Found
{
    "errors": "Service not found"
}

// 400 Bad Request - User Rental Limit Reached
{
    "errors": "You have reached the maximum number of active rentals"
}

// 400 Bad Request - Out of Stock (General)
{
    "errors": "Service is out of stock"
}

// 400 Bad Request - Out of Stock (Specific Carrier)
{
    "errors": "Service is out of stock for selected carrier: at&t"
}

// 400 Bad Request - Out of Stock (Carrier + Area Codes)
{
    "errors": "Service is out of stock for selected carrier and area codes"
}

// 400 Bad Request - Out of Stock (Area Codes)
{
    "errors": "Service is out of stock for selected area codes"
}

// 400 Bad Request - Service Not Available for User
{
    "errors": "Service is not available"
}

// 400 Bad Request - Insufficient Funds (Base Price)
{
    "errors": "Insufficient funds"
}

// 400 Bad Request - Insufficient Funds (With Extra Charges)
{
    "errors": "Insufficient funds for area code extra charge"
}

// 400 Bad Request - Price Exceeds Maximum
{
    "errors": "The price of the service exceeds the maximum price you are willing to pay, actual price is: 1.25"
}

// 408 Request Timeout - Number Already Taken
{
    "errors": "Rental error, number is already taken. Please try again"
}

// 429 Too Many Requests
{
    "errors": "Rental error, number is already taken. Please try again"
}

Important Notes

// 1. Rate limit: 2 request per second
// 4. Area codes must be comma-separated without spaces
// 5. Keep_carrier forces strict carrier matching (may fail if unavailable)
// 6. Lock_area_code forces strict area code matching (may fail if unavailable)
// 7. Price increases apply: carrier OR area code = +20%, both = +40%

POST /api/v1/rent-multiple-services

This endpoint allows you to rent multiple services on the same phone number simultaneously. Provide a comma-separated list of service codes. All services must be available on the same number, or the request will fail and be cached. (1 Request per second)

Request Body

{
    "services": "whatsapp,telegram,instagram",
    "max_price" // OPTIONAL: 3.00,
    "carrier" // OPTIONAL: "at&t"
    "keep_carrier" // OPTIONAL: "true"
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/rent-multiple-services \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "services": "whatsapp,telegram,instagram", "max_price": 3.00 }'

Successful Response (201 CREATED)

{
    "status": "success",
    "rentals": [
        {
            "id": 12345,
            "status": "success",
            "message": "Number rented successfully.",
            "errors": null,
            "end_time": "2025-07-06 15:43:37"
            "number": "1234567890"
            "service_name": "Whatsapp"
            "price": "0.55"
        },
        {
            "id": 12346,
            "status": "success",
            "message": "Number rented successfully.",
            "errors": null,
            "end_time": "2025-07-06 15:43:37"
            "number": "1234567890"
            "service_name": "Telegram"
            "price": "0.45"
        },
        {
            "id": 12347,
            "status": "success",
            "message": "Number rented successfully.",
            "errors": null,
            "end_time": "2025-07-06 15:43:37"
            "number": "1234567890"
            "service_name": "Instagram"
            "price": "0.50"
        }
    ],
    "new_balance": "111.82",
    "total_cost": "1.50"
}

Important: If at least one service is unavailable on the same number, the entire request fails and the service combination is cached for 5-15 minutes to prevent repeated failed attempts.

POST /api/v1/cancel-rental

Use this endpoint to cancell a rental. You must wait 1 min before request a cancellation. (1 Request per second)

Request Body

{
    "id": 1234
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/cancel-rental \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "id": 1234 }'

Successful Response (200 OK)

{
    "id": 12345,
    "status": "cancelled",
    "code": null,
    "errors": null,
    "end_time": "2025-07-06 15:43:37"
    "number": "1234567890"
    "service_name": "Whatsapp"
    "cost": "0.55"
    "balance": "113.87"
}

POST /api/v1/rental-status

Use this endpoint to retrieve the status of a specific rental.

Request Body

{
    "id": 1234
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/rental-status \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "id": 1234 }'

Successful Response (200 OK)

{
    "id": 12345,
    "status": "active",
    "code": null,
    "errors": null,
    "end_time": "2025-07-06 15:43:37"
    "number": "1234567890"
    "service_name": "Whatsapp"
    "cost": "0.55"
    "balance": "113.32"
}

POST /api/v1/rental-status/{id}/completed

Use this endpoint to mark a specific rental as completed.

Example cURL Request

curl -X POST https://getatext.com/api/v1/rental-status/{id}/completed \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \

Successful Response (200 OK)

{
    "status": "success",
    "message": "Rental marked as completed successfully.",
    "errors": "null",
    "rental": {
        "id": 12345,
        "end_time": "2025-08-12 00:19:30",
        "number": "1234567890",
        "service_name": "Whatsapp",
        "price": "0.1",
        "new_balance": "9.9"
    }
}

GET /api/v1/prices-info

Use this endpoint to retrieve the available services in the platform.

Example cURL Request

curl -X GET https://getatext.com/api/v1/prices-info \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \'

Successful Response (200 OK)

{
    "service_name": "Whatsapp",
    "api_name": "whatsapp",
    "multiple_sms": "true",
    "price": "0.55",
    "ttl": 5,
    "stock": 66,
}

POST /api/v1/re-rent

Use this endpoint to retrieve the available services in the platform.

Request Body

{
    "rental_id": 1234
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/re-rent \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "rental_id": 1234 }'

Successful Response (201 OK)

{
    "id": 12345,
    "status": "success",
    "message": "Number rented successfully.",
    "errors": null,
    "end_time": "2025-07-06 15:43:37"
    "number": "1234567890"
    "service_name": "Whatsapp",
    "price": "0.55",
    "new_balance": "113.32"
}

GET /api/v1/balance

Use this endpoint to retrieve the user's balance.

Example cURL Request

curl -X GET https://getatext.com/api/v1/balance \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \'

Successful Response (200 OK)

{
    "status": "success",
    "balance": "10.55",
    "errors": "null",
}

GET /api/v1/long-rentals

Use this endpoint to retrieve the user's long rentals.

Example cURL Request

curl -X GET https://getatext.com/api/v1/long-rentals \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \'

Successful Response (200 OK)

{
    "status": "success",
    "long_rentals": [
        {
            "id": 1,
            "number": "1234567890",
            "end_time": "2025-07-06",
            "rented_at": "2025-07-01",
            "price": "10.55",
            "status": "Active",
            "period":  "1 Week",
            "auto_renew": true
        },
        ....
        ],
    "errors": "null",
}

POST /api/v1/long-rentals

Use this endpoint to create a new long rental.

Request Body

{
    "auto_renew": true,
    "rental_time": "1w"
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/long-rentals \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "auto_renew": true,
    "rental_time": "1w", // Can be "1w", "2w", "1m", "1y"
}'

Successful Response (200 OK)

{
    "status": "success",
    "long_rental": 
            "id": 1,
            "number": "1234567890",
            "end_time": "2025-07-06",
            "rented_at": "2025-07-01",
            "price": "10.55",
            "status": "Active",
            "period":  "1 Week",
            "auto_renew": true,
    "errors": "null",
}

POST /api/v1/long-rentals/{id}/update

Use this endpoint to update an existing long rental.

Request Body

{
    "action": "renew",
    "auto_renew": true
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/long-rentals/{id}/update \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "action": "renew", // or "cancel", "auto_renew"
    "auto_renew": true, // Optional, only for "auto_renew" action
}'

Successful Response (200 OK)

{
    "status": "success",
    "long_rental": 
            "id": 1,
            "number": "1234567890",
            "end_time": "2025-07-06",
            "rented_at": "2025-07-01",
            "price": "10.55",
            "status": "Active",
            "period":  "1 Week",
            "auto_renew": true,
    "errors": "null",
}

GET /api/v1/long-rentals/{id}/messages

Use this endpoint to retrieve messages for a specific long rental.

Example cURL Request

curl -X GET https://getatext.com/api/v1/long-rentals/{id}/messages \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \

Successful Response (200 OK)

{
    "status": "success",
    "messages": [
        {
            "message": "This is a example message",
            "number": "1234567890",
            "rented_at": "2025-07-28T12:39:32-04:00",
            "sender": "8888",
        },
        ....
        ],
    "errors": "null",
}

GET /stubs/handler_api.php

Legacy GET-based API compatible with third-party integrations. All parameters are passed as query string values. Authenticate using api_key and select the operation with action.

Base Request

curl -X GET "https://getatext.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=ACTION&..." \
-H "Content-Type: application/json"

action=getNumber — Rent a number

// Required
service=whatsapp

// Optional filters
carrier=at%26t          // "at&t" or "tmobile"
keep_carrier=true       // Fail if carrier unavailable
area_codes=212,646      // Comma-separated area codes
lock_area_code=true     // Fail if no number in given area codes
max_price=1.00          // Skip if real price exceeds this

// Price multipliers (same as /api/v1/rent-a-number):
// Carrier match only OR area code only: ×1.2
// Both carrier and area code match:     ×1.4

// Response
ACCESS_NUMBER:12345:11234567890   // id:1{number}
OUT_OF_STOCK
INSUFFICIENT_FUNDS
MAX_RENTALS_EXCEEDED
BAD_SERVICE
SERVICE_NOT_AVAILABLE
APPROVAL_REQUIRED
MAX_PRICE_EXCEEDED
RENTAL_ERROR
RENTAL_ERROR_TRY_AGAIN
MAINTENANCE

action=getStatus — Poll for received SMS code

// Required
id=12345

// Response
STATUS_OK:654321     // Code received
STATUS_WAIT_CODE     // Still waiting
NO_ACTIVATION
BAD_ID

action=setStatus — Cancel (8) or mark completed (6)

// Required
id=12345
status=8   // 8 = cancel rental
status=6   // 6 = mark rental as completed (rental must be in "viewed" status)

// Response for status=8
ACCESS_CANCEL
RENTAL_LOCKED    // Must wait 1 minute after creation
NO_ACTIVATION

// Response for status=6
ACCESS_ACTIVATION
NO_ACTIVATION

action=getBalance — Retrieve account balance

// No extra parameters needed

// Response
ACCESS_BALANCE:100.50
BAD_KEY
MAINTENANCE

action=getExtraActivation — Re-rent the same number from a previous rental

// Required
id=12345   // ID of the original (non-active) rental

// Cost: original cost, or 50% if user has a prior completed rental for that number+service

// Response
ACCESS_NUMBER:12346:11234567890   // new_id:1{number}
OUT_OF_STOCK
INSUFFICIENT_FUNDS
RENTAL_ACTIVE    // Original rental is still active
NO_ACTIVATION
BAD_SERVICE      // "Not Listed - Generic" services cannot be re-rented
MAINTENANCE

action=getPrices — Query price and stock for one or more services

// Required
service=whatsapp,telegram   // Comma-separated api_names
country=187                 // Must always be 187

// Response (JSON array)
[
  {
    "whatsapp": {
      "cost": 0.55,
      "count": 1200,
      "physicalCount": 1200
    }
  },
  {
    "telegram": {
      "cost": 0.45,
      "count": 980,
      "physicalCount": 980
    }
  }
]

BAD_COUNTRY   // country != 187
BAD_SERVICE   // service param missing
MAINTENANCE

GET /api/v1/auctions

Retrieve all active auctions currently available for bidding.

Example cURL Request

curl -X GET https://getatext.com/api/v1/auctions \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json"

Successful Response (200 OK)

{
    "status": "success",
    "auctions": [
        {
            "id": 1,
            "service_name": "Whatsapp",
            "current_bid": "0.55",
            "end_time": "2026-02-02 18:30:00",
            "amount": 100
        }
    ]
}

POST /api/v1/auctions/{id}/bid

Place a bid on an active auction. Your bid must be higher than the current bid, and you must have sufficient balance to cover the total cost (bid amount × quantity).

Request Body

{
    "bid_amount": 0.60
}

Example cURL Request

curl -X POST https://getatext.com/api/v1/auctions/1/bid \
-H "Auth: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "bid_amount": 0.60 }'

Successful Response (200 OK)

{
    "status": "success",
    "message": "Bid placed successfully.",
    "new_current_bid": "0.60"
}

Error Responses:

// Bid too low (400)
{
    "errors": "Your bid must be higher than the current bid"
}

// Insufficient balance (400)
{
    "errors": "Insufficient funds for this bid"
}

// Auction not found (404)
{
    "errors": "Auction not found or is no longer active"
}

POST Webhook

Also, you can configure a webhook in your profile, so we can send codes when our platform receives it. Note: we send webhooks from many different IP addresses, so it's recommended to use a dynamic IP whitelist or other security measures.

Webhook Request to Your Endpoint:

{
    "id": 12345,
    "code": 654321,
    "received_at": "2025-07-06 15:43:37"
    "number": "1234567890"
    "service_name": "Whatsapp"
    "status": "active"
    "cost": "0.91"
}

API Docs

Authentication

POST /api/v1/rent-a-number

POST /api/v1/rent-multiple-services

POST /api/v1/cancel-rental

POST /api/v1/rental-status

POST /api/v1/rental-status/{id}/completed

GET /api/v1/prices-info

POST /api/v1/re-rent

GET /api/v1/balance

GET /api/v1/long-rentals

POST /api/v1/long-rentals

POST /api/v1/long-rentals/{id}/update

GET /api/v1/long-rentals/{id}/messages

GET /stubs/handler_api.php

GET /api/v1/auctions

POST /api/v1/auctions/{id}/bid

POST Webhook