API Docs

Welcome to the Getatext API. Here you'll find all the information you need to integrate our services into your applications. Automate SMS verifications with ease.

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-specific-number

This endpoint allows you to rent a specific phone number (that you choose) for a specific service, instead of letting the system pick a random number. A flat +20% surcharge applies to the base price. If you have previously rented this exact number for the same service and the rental was completed, a returning-customer discount is applied (half of your original cost for that number × 1.20 surcharge). Shares the same throttle group as /api/v1/rent-a-number.

Request Body Parameters

{ "number": "1234567890", // REQUIRED: Exact phone number you want to rent "service": "whatsapp", // REQUIRED: Service API name "max_price": 1.50 // OPTIONAL: Maximum final price (including +20% surcharge) willing to pay }

Pricing Notes

// Price calculation: // - New rental: base service price × 1.20 (flat +20% specific-number surcharge) // - Returning customer (previously completed rental for same number + service): // (original_cost / 2) × 1.20 // - max_price is compared against the FINAL cost (after the +20% surcharge) // - Carrier / area code multipliers do NOT apply here; you chose the number yourself

Example cURL Request

curl -X POST https://getatext.com/api/v1/rent-specific-number \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "number": "1234567890", "service": "whatsapp", "max_price": 1.50 }'

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.66, "new_balance": 113.32, "country": "usa", "returning_customer": false }

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 number or service { "errors": "Phone number and service are required" } // 400 Bad Request - Global Rental Limit Reached { "errors": "The maximum number of active rentals as reached" } // 404 Not Found - Service Not Found { "errors": "Service not found" } // 400 Bad Request - Service Requires Prior Approval { "errors": "This service requires prior approval. Please request access through the platform portal before renting." } // 400 Bad Request - User Rental Limit Reached { "errors": "You have reached the maximum number of active rentals" } // 404 Not Found - Number Not Available { "errors": "This number does not exist in our system or is not available" } // 400 Bad Request - Number Already Used/Taken For This Service { "errors": "This number is unavailable for you. Please try a different number" } // 400 Bad Request - Invalid Price { "errors": "Invalid price for this service" } // 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" } // 400 Bad Request - Insufficient Funds { "errors": "Insufficient funds" }

Important Notes

// 1. Shares the rentNumber throttle group with /api/v1/rent-a-number // 2. You must pass the exact phone number (no formatting, digits only as stored in our system) // 3. A flat +20% surcharge ALWAYS applies on top of the base service price // 4. Returning customers (same number + service previously completed) get a 50% base discount before the +20% surcharge // 5. The number must be in our active pool and not already in use for that service by another user // 6. Carrier / area_code / keep_carrier / lock_area_code parameters are NOT supported here — use /api/v1/rent-a-number for filtered random selection

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", // REQUIRED: Comma-separated service API names "max_price": 3.00, // OPTIONAL: Maximum total price willing to pay "carrier": "at&t", // OPTIONAL: Preferred carrier "keep_carrier": true, // OPTIONAL: Force carrier match (boolean) "rent_area_codes": "212,646", // OPTIONAL: Comma-separated area codes. Overrides the dashboard-configured area codes. "lock_area_code": true // OPTIONAL: Fail if no number is available in the requested area codes. Overrides the dashboard setting. }

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, "rent_area_codes": "212,646", "lock_area_code": true }'

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. If immediate cancellation is disabled for your account or for the rented service, you must wait 5 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, "cashback": false }

cashback is true when the service currently has an open cashback mission. Enroll from the Missions page to earn a percentage of your spend back as credit.

POST /api/v1/prices-info-stock

Use this endpoint to retrieve the available stock of a service broken down by area code. The breakdown is recalculated every few minutes; if it is not ready yet the endpoint answers 503 and you can simply retry shortly after.

Request Body Parameters

{ "service": "whatsapp" // REQUIRED: Service API name }

Example cURL Request

curl -X POST https://getatext.com/api/v1/prices-info-stock \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "whatsapp" }'

Successful Response (200 OK)

{ "status": "success", "errors": null, "service": "whatsapp", "stock": { "555": 9, "852": 3 } }

Each key of stock is an area code and its value is how many numbers with that area code are currently available for the service. Area codes with no available numbers are omitted. Use the codes you want with the area_codes parameter of /api/v1/rent-a-number.

Error Responses

// 422 Unprocessable Entity - Missing service { "errors": "The service field is required" } // 404 Not Found - Unknown service API name { "errors": "Service not found" } // 503 Service Unavailable - Breakdown not calculated yet, retry in a few minutes { "status": "error", "errors": "Stock is being calculated, please try again in a few minutes" }

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/prices

Retrieve the available long rental pricing and current stock. Prices are fixed; stock is the number of pool numbers currently available for a new long rental.

Example cURL Request

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

Successful Response (200 OK)

{ "status": "success", "prices": { "1w": 10.99, "2w": 12.99, "1m": 14.99 }, "stock": 42, "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. Optionally include area_codes to restrict the assigned number to a specific set of US area codes (comma-separated string or array). When provided in the request, it takes priority over the account's default area codes configured in the user settings. If omitted, the account default will be used (if any). Selecting by area code adds a 20% surcharge to the rental price.

Request Body

{ "auto_renew": true, "rental_time": "1w", "area_codes": "305,786,407" }

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" "area_codes": "305,786,407" // Optional. Comma-separated string or array of area codes. Overrides the account default. }'

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 /api/v1/long-rentals/retakeable

List the expired long rentals whose number can still be recovered ("retaken"). A number only shows up here while it is still live on our platform and nobody else has taken it, so the list is the authoritative answer on what can be recovered right now. Each entry carries the periods you may pick and the total for each one, reactivation fee included.

Example cURL Request

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

Successful Response (200 OK)

{ "status": "success", "retake_fee": 0.3, "long_rentals": [ { "id": 1, "number": "1234567890", "period": "1 Week", "expired_at": "2026-08-28", "fee": 0.3, "periods": [ { "value": "1w", "label": "1 Week", "cost": 10.99, "fee": 0.3, "total": 11.29 }, { "value": "2w", "label": "1 Biweek", "cost": 12.99, "fee": 0.3, "total": 13.29 }, { "value": "1m", "label": "1 Month", "cost": 14.99, "fee": 0.3, "total": 15.29 } ] } ], "errors": null }

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

Recover an expired long rental on the very same number. Pass the id of the expired rental; you may pick any period, it does not have to match the original one. A brand new long rental is created (the expired record is kept untouched, so the lapse stays visible in your history) and a single debit is charged for the period plus a flat $0.30 reactivation fee. The fee is charged once and is not refunded if the rental is later cancelled.

Call /api/v1/long-rentals/retakeable first: if the number is gone the retake is rejected with 422.

A number is only recoverable by the account that held it:

  • The rental id must belong to your account. Anyone else's id answers 404, exactly as an id that does not exist.
  • You must have been the last account to hold the number. Once a rental lapses the number goes back to the pool, and if somebody else rented it in the meantime it can no longer be recovered by you, even after they let it go too.
  • A lapse is recovered once. After a successful retake, recover from the new rental, not from the old one.

Request Body

{ "rental_time": "1w", // REQUIRED: 1w, 2w or 1m "auto_renew": true // OPTIONAL: defaults to false }

Example cURL Request

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

Successful Response (201 Created)

{ "status": "success", "message": "Long rental retaken successfully.", "long_rental": { "id": 42, "number": "1234567890", "end_time": "2026-09-09", "rented_at": "2026-09-02", "price": "10.99", "status": "Active", "period": "1 Week", "auto_renew": true, "retake_of_id": 1, "retake_fee": "0.30" }, "errors": null }

Error Responses

// 404 - The rental does not exist or is not yours { "errors": "Long rental not found" } // 422 - The rental is still active, renewed or cancelled { "errors": "Only an expired long rental can be retaken" } // 422 - The number was rotated away or taken by someone else { "errors": "This number is no longer available to retake." } // 422 - Unknown rental_time { "errors": "Invalid rental period provided." } // 400 - Balance below the period cost + the $0.30 fee { "errors": "Insufficient funds." }

GET /api/v1/service-long-rentals/prices

Retrieve the available pricing for service long rentals. Prices are grouped by service and list every period (1d, 3d, 7d, 14d, 30d) configured for that service.

Example cURL Request

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

Successful Response (200 OK)

{ "status": "success", "service_long_rental_prices": [ { "service_name": "Whatsapp", "api_name": "whatsapp", "prices": [ { "period": "1d", "cost": "1.50" }, { "period": "3d", "cost": "3.00" }, { "period": "7d", "cost": "5.00" }, { "period": "14d", "cost": "9.00" }, { "period": "30d", "cost": "15.00" } ] } ], "errors": null }

GET /api/v1/service-long-rentals

Retrieve all of your active service long rentals. Service long rentals reserve a number for a specific service for an extended period (1d, 3d, 7d, 14d, or 30d).

Example cURL Request

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

Successful Response (200 OK)

{ "status": "success", "service_long_rentals": [ { "id": 1, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-04-26", "rented_at": "2026-04-19", "cost": "5.00", "status": "Active", "period": "7 Days", "auto_renew": true } ], "errors": null }

POST /api/v1/service-long-rentals

Rent a number for a specific service over a long period. The cost is determined by the platform's service long rental price configuration. Balance is validated before assigning a number.

Request Body Parameters

{ "service": "whatsapp", // REQUIRED: Service api_name "period": "7d", // REQUIRED: 1d, 3d, 7d, 14d or 30d "auto_renew": true, // OPTIONAL: enable auto renewal "area_codes": "212,646", // OPTIONAL: Comma-separated area codes. Overrides the dashboard-configured area codes. "lock_area_code": true // OPTIONAL: Fail if no number is available in the requested area codes. Overrides the dashboard setting. }

Example cURL Request

curl -X POST https://getatext.com/api/v1/service-long-rentals \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "whatsapp", "period": "7d", "auto_renew": true, "area_codes": "212,646", "lock_area_code": true }'

Successful Response (201 CREATED)

{ "status": "success", "message": "Service long rental created successfully.", "service_long_rental": { "id": 1, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-04-26", "rented_at": "2026-04-19", "cost": "5.00", "status": "Active", "period": "7 Days", "auto_renew": true }, "errors": null }

Error Responses

// 403 - Service long rentals disabled for the account { "errors": "Service long rentals are not enabled for this account" } // 400 - Missing service / period { "errors": "Service is not presented on the request" } { "errors": "Period is not presented on the request" } // 422 - Invalid period { "errors": "Invalid period. Allowed values: 1d, 3d, 7d, 14d, 30d" } // 404 - Service not found { "errors": "Service not found" } // 422 - Service not configured for the requested period { "errors": "This service is not available for long rental in the selected period" } // 400 - Insufficient funds { "errors": "Insufficient funds" } // 422 - No pool number available { "errors": "No available pool number for service long rental" }

POST /api/v1/service-long-rentals/{number}/cancel

Cancel a service long rental using the assigned phone number. Cancellation is only allowed if the rental has not yet received any messages and is still inside the cancellation window. If the same number is rented for multiple services, include the service parameter to disambiguate.

Optional Body Parameter

{ "service": "whatsapp" // OPTIONAL: only required if multiple services exist on the same number }

Example cURL Request

curl -X POST https://getatext.com/api/v1/service-long-rentals/1234567890/cancel \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "whatsapp" }'

Successful Response (200 OK)

{ "status": "success", "message": "Service long rental cancelled successfully.", "service_long_rental": { "id": 1, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-04-26", "rented_at": "2026-04-19", "cost": "5.00", "status": "Cancelled", "period": "7 Days", "auto_renew": true }, "errors": null }

Error Responses

// 404 - No active rental found { "errors": "Service long rental not found" } // 400 - Multiple rentals on the same number { "errors": "Multiple active service long rentals found for this number. Provide the \"service\" parameter to disambiguate." } // 422 - Cannot cancel (already received messages or window expired) { "errors": "Service long rental cannot be cancelled (already received messages or cancellation window expired)" }

POST /api/v1/service-long-rentals/{number}/auto-renew

Enable or disable auto-renewal for an active service long rental, identified by the assigned phone number. When auto-renewal is enabled, the rental will be automatically renewed at expiration as long as the account has sufficient balance. If the same number is rented for multiple services, include the service parameter to disambiguate.

Body Parameters

{ "auto_renew": true, // REQUIRED: true to enable, false to disable "service": "whatsapp" // OPTIONAL: only required if multiple services exist on the same number }

Example cURL Request

curl -X POST https://getatext.com/api/v1/service-long-rentals/1234567890/auto-renew \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "auto_renew": true, "service": "whatsapp" }'

Successful Response (200 OK)

{ "status": "success", "message": "Service long rental auto-renew updated successfully.", "service_long_rental": { "id": 1, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-04-26", "rented_at": "2026-04-19", "cost": "5.00", "status": "Active", "period": "7 Days", "auto_renew": true }, "errors": null }

Error Responses

// 400 - Missing auto_renew parameter { "errors": "auto_renew is not presented on the request" } // 422 - auto_renew is not a valid boolean { "errors": "auto_renew must be a boolean" } // 404 - No active rental found { "errors": "Service long rental not found" } // 400 - Multiple rentals on the same number { "errors": "Multiple active service long rentals found for this number. Provide the \"service\" parameter to disambiguate." }

POST /api/v1/service-long-rentals/{number}/renew

Manually renew an active service long rental, identified by the assigned phone number. The rental's end date is extended by its original duration and the same cost is charged again to the account balance. If the same number is rented for multiple services, include the service parameter to disambiguate.

Optional Body Parameter

{ "service": "whatsapp" // OPTIONAL: only required if multiple services exist on the same number }

Example cURL Request

curl -X POST https://getatext.com/api/v1/service-long-rentals/1234567890/renew \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "whatsapp" }'

Successful Response (200 OK)

{ "status": "success", "message": "Service long rental renewed successfully.", "service_long_rental": { "id": 1, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-05-03", "rented_at": "2026-04-19", "cost": "5.00", "status": "Active", "period": "7 Days", "auto_renew": true }, "errors": null }

Error Responses

// 404 - No active rental found { "errors": "Service long rental not found" } // 400 - Multiple rentals on the same number { "errors": "Multiple active service long rentals found for this number. Provide the \"service\" parameter to disambiguate." } // 400 - Insufficient balance to renew { "errors": "Insufficient funds" }

GET /api/v1/service-long-rentals/{number}/messages

Retrieve all messages received for a service long rental, identified by the assigned phone number. If the same number is rented for multiple services, include the service query parameter.

Example cURL Request

curl -X GET "https://getatext.com/api/v1/service-long-rentals/1234567890/messages?service=whatsapp" \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json"

Successful Response (200 OK)

{ "status": "success", "messages": [ { "message": "Your Whatsapp code is 123456", "sender": "8888", "received_at": "2026-04-19T12:39:32-04:00", "number": "1234567890", "service_name": "Whatsapp" } ], "errors": null }

Error Responses

// 404 - No active rental found { "errors": "Service long rental not found" } // 400 - Multiple rentals on the same number { "errors": "Multiple active service long rentals found for this number. Provide the \"service\" parameter to disambiguate." }

GET /api/v1/service-long-rentals/retakeable

List the expired service long rentals whose number can still be recovered ("retaken"). A number only shows up here while it is still live on our platform and no one holds an active rental of that same service on it. Each entry carries the durations configured for the service and the total for each one, reactivation fee included.

Example cURL Request

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

Successful Response (200 OK)

{ "status": "success", "retake_fee": 0.3, "service_long_rentals": [ { "id": 7, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "period": "7 Days", "expired_at": "2026-08-28", "fee": 0.3, "periods": [ { "value": "7d", "label": "7 Days", "cost": 5, "fee": 0.3, "total": 5.3 }, { "value": "30d", "label": "30 Days", "cost": 15, "fee": 0.3, "total": 15.3 } ] } ], "errors": null }

POST /api/v1/service-long-rentals/{number}/retake

Recover an expired service long rental on the very same number and service, identified by the phone number. You may pick any duration configured for the service, it does not have to match the original one. A brand new rental is created (the expired record is kept untouched) and a single debit is charged for the duration plus a flat $0.30 reactivation fee. The fee is charged once and is not refunded if the rental is later cancelled.

If the number has expired rentals for more than one service, include the service parameter to disambiguate.

A number is only recoverable by the account that held it:

  • The number must carry an expired rental of your account for that service. Anything else answers 404.
  • You must have been the last account to hold the number for that service. Service long rentals legitimately share one number across accounts, one per service, so another account holding a different service on it does not block you — but another account having taken your service on it does, permanently.
  • A lapse is recovered once. After a successful retake, recover from the new rental, not from the old one.

Request Body

{ "period": "7d", // REQUIRED: any duration configured for the service "service": "whatsapp", // OPTIONAL: only if the number has expired rentals for several services "auto_renew": true // OPTIONAL: defaults to false }

Example cURL Request

curl -X POST https://getatext.com/api/v1/service-long-rentals/1234567890/retake \ -H "Auth: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "period": "7d", "service": "whatsapp", "auto_renew": true }'

Successful Response (201 Created)

{ "status": "success", "message": "Service long rental retaken successfully.", "service_long_rental": { "id": 88, "number": "1234567890", "service_name": "Whatsapp", "api_name": "whatsapp", "end_time": "2026-09-09", "rented_at": "2026-09-02", "cost": "5.00", "status": "Active", "period": "7 Days", "auto_renew": true, "retake_of_id": 7, "retake_fee": "0.30" }, "errors": null }

Error Responses

// 404 - No expired rental found on that number { "errors": "Expired service long rental not found" } // 400 - Expired rentals for several services on the same number { "errors": "Multiple expired service long rentals found for this number. Provide the \"service\" parameter to disambiguate." } // 422 - The number was rotated away or taken by someone else { "errors": "This number is no longer available to retake." } // 422 - The service is not sold for that duration { "errors": "Invalid rental period provided." } // 400 - Balance below the duration cost + the $0.30 fee { "errors": "Insufficient funds." }

GET /stubs/handler_api.php

Drop-in compatible API for third-party integrations written against the standard handler_api.php protocol (5sim, sms-man, sms-activate, smshub). All parameters are passed as query string values on GET or POST. Authenticate using api_key and select the operation with action. Rate limit: 20 requests per second per API key, exceeding it returns ACCESS_REQUEST_EXCEEDED.

We only sell US numbers. The country parameter is optional and accepts usa, us, united states or 187; any other country returns NO_NUMBERS on getNumber and an empty object on the listing actions. The operator parameter is an alias of our carrier and accepts any, at&t and tmobile (an unknown operator falls back to any).

Base Request

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

Error strings

BAD_KEY // Unknown API key, or the account is not enabled BAD_ACTION // Unknown action, or the action is not available for your account BAD_SERVICE // Unknown service, or a carrier value we do not sell BAD_STATUS // Unsupported status value on setStatus NO_NUMBERS // Nothing we can rent you right now (see X-Error-Reason) NO_BALANCE // Not enough funds NO_ACTIVATION // The activation does not exist, or is not in a state that allows the operation WRONG_ACTIVATION_ID // Missing or non-numeric id EARLY_CANCEL_DENIED // Cancellation requested before the 5 minute lock elapsed ERROR_SQL // The rental could not be created, safe to retry MAINTENANCE // Platform under maintenance (no equivalent in the standard protocol) ACCESS_REQUEST_EXCEEDED // Rate limit (no equivalent in the standard protocol) // The protocol has a small error vocabulary, so several distinct refusals answer // NO_NUMBERS. The precise cause is returned in the X-Error-Reason response header: // OUT_OF_STOCK, MAX_RENTALS_EXCEEDED, SERVICE_NOT_AVAILABLE, APPROVAL_REQUIRED, // MAX_PRICE_EXCEEDED, RENTAL_ACTIVE, BAD_COUNTRY or FORWARD_NOT_SUPPORTED.

action=getNumber — Rent a number

// Required service=whatsapp // Standard optional parameters country=usa // usa, us, united states or 187. Anything else returns NO_NUMBERS operator=tmobile // any, at&t or tmobile. Unknown operators fall back to "any" forward=0 // Call forwarding is not offered; forward=1 returns NO_NUMBERS maxPrice=1.00 // Alias of max_price ref, phoneException, freePrice, verification // Accepted and ignored // Our own optional filters carrier=at%26t // "at&t" or "tmobile". Takes priority over operator, and a wrong value fails 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} NO_NUMBERS NO_BALANCE BAD_SERVICE ERROR_SQL MAINTENANCE

action=getNumberV2 — Rent a number, JSON response

// Same parameters, same rules and same error strings as getNumber // Response { "activationId": "12345", "phoneNumber": "11234567890", "activationCost": "0.55", "countryCode": "187", "canGetAnotherSms": true, "activationTime": "2026-08-22 15:43:37", "activationOperator": "tmobile" }

action=getStatus — Poll for received SMS code

// Required id=12345 // Response STATUS_OK:654321 // Code received (the most recent one) STATUS_WAIT_CODE // Still waiting STATUS_WAIT_RETRY:654321 // Another SMS was requested with setStatus=3; carries the previous code STATUS_CANCEL // Cancelled, expired, or timed out without a code NO_ACTIVATION WRONG_ACTIVATION_ID // STATUS_WAIT_RESEND is never returned: the platform has no resend step.

action=getFullSms — Retrieve the full message text

// Required id=12345 // Response FULL_SMS:Your Whatsapp code is 654321 STATUS_WAIT_CODE // No message yet STATUS_CANCEL NO_ACTIVATION BAD_ACTION // The account is not allowed to read message bodies

action=setStatus — Update the activation

// Required id=12345 status=1 // 1 = number is ready to receive the SMS (acknowledged, changes nothing) status=3 // 3 = request another SMS on the same activation status=6 // 6 = mark rental as completed (rental must be in "viewed" status) status=8 // 8 = cancel rental status=-1 // -1 = cancel rental (same as 8) // Response per status 1 -> ACCESS_READY | NO_ACTIVATION 3 -> ACCESS_RETRY_GET | NO_ACTIVATION | BAD_STATUS 6 -> ACCESS_ACTIVATION | NO_ACTIVATION 8 -> ACCESS_CANCEL | NO_ACTIVATION | EARLY_CANCEL_DENIED -1 -> ACCESS_CANCEL | NO_ACTIVATION | EARLY_CANCEL_DENIED // status=3 requires an activation that already received a code, is still within // its rental time, and belongs to a service (or an account) that accepts multiple // SMS. Otherwise it answers BAD_STATUS. After it, getStatus returns // STATUS_WAIT_RETRY until a new message arrives.

action=getBalance — Retrieve account balance

// No extra parameters needed // Response ACCESS_BALANCE:100.50 BAD_KEY MAINTENANCE

action=getBalanceAndCashBack — Balance with cashback field

// No extra parameters needed. We run no cashback programme, so it is always 0.00 // Response ACCESS_BALANCE:100.50:0.00

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} NO_NUMBERS // Out of stock, or the original rental is still active NO_BALANCE NO_ACTIVATION WRONG_ACTIVATION_ID BAD_SERVICE // "Not Listed - Generic" services cannot be re-rented ERROR_SQL MAINTENANCE

action=getPrices — Query price and stock

// All parameters optional service=whatsapp,telegram // Comma-separated api_names. Omit it for the whole catalogue country=usa // usa, us, united states or 187 // Response. cost/count sit on the service itself and are repeated under an // "any" operator, so clients written for either convention can read it. The same // block is served under the "usa" and "187" country keys. { "usa": { "whatsapp": { "cost": 0.55, "count": 1200, "any": { "cost": 0.55, "count": 1200 } }, "telegram": { "cost": 0.45, "count": 980, "any": { "cost": 0.45, "count": 980 } } }, "187": { ... identical ... } } {} // Any country other than the US MAINTENANCE

action=getPrices with country=187 — Legacy response

// Passing the numeric 187 keeps the original response of this endpoint, so // integrations already built against it are unaffected. service is required here. service=whatsapp,telegram country=187 // Response (JSON array) [ { "whatsapp": { "cost": 0.55, "count": 1200, "physicalCount": 1200 } }, { "telegram": { "cost": 0.45, "count": 980, "physicalCount": 980 } } ] BAD_SERVICE // service param missing

action=getNumbersStatus — Available numbers per service

// Optional country=usa // Any other country returns {} // Response. The _0 suffix means "without call forwarding"; we have no forwarding // numbers, so _1 is never reported. Counts are strings, as in the standard protocol. { "whatsapp_0": "1200", "telegram_0": "980" }

action=getCountries — Supported countries

// No extra parameters needed. We serve the US only, listed under both keys. { "187": { "id": 187, "rus": "США", "eng": "USA", "chn": "美国", "visible": 1, "retry": 1, "rent": 0, "multiService": 0 }, "usa": { ... identical ... } }

action=getOperators — Carriers available

// Optional country=usa // Response { "countryOperators": { "187": ["any", "at&t", "tmobile"], "usa": ["any", "at&t", "tmobile"] } } {"status":"error","error":"OPERATORS_NOT_FOUND"} // Any other country

action=getActiveActivations — List your running activations

// No extra parameters needed // Response { "status": "success", "activeActivations": [ { "activationId": "12345", "serviceCode": "whatsapp", "phoneNumber": "11234567890", "activationCost": "0.55", "activationStatus": "1", "smsCode": "", "smsText": "", "activationTime": "2026-08-22 15:43:37", "discount": "0", "repeated": "0", "countryCode": "187", "countryName": "usa", "canGetAnotherSms": "0", "canGetAnotherSMS": "0" } ] } {"status":"error","error":"NO_ACTIVATIONS"} // Nothing running // activationStatus is "1" while waiting for the SMS and "3" once it arrived. // smsText is empty unless the account is allowed to read message bodies. // canGetAnotherSms is emitted in both spellings for client compatibility.

action=getTopCountriesByService — Price and stock of a service

// Required service=whatsapp // Response. One country, so the top has a single position. { "0": { "country": 187, "count": 1200, "price": 0.55, "retail_price": 0.55 } } {} // Unknown service BAD_SERVICE // service param missing

GET /api/record

Public code-by-URL polling endpoint, drop-in compatible with the number|url pair protocol used by sms8-style resellers. Each rental gets its own 36-character token, so the pair can be handed to an end user who polls for the verification code without ever seeing your API key. Requires account enablement: contact support to activate Code By URL. Once enabled, every new rental (regular and service long rental) returns record_url, record_pair and number_url_format in its creation and status responses; without it all three fields are null. Rentals created before activation have no URL. The number in the pair is always written in full international form, with its +1.

No Auth header: the token is the only credential. Always responds HTTP 200. Rate limit: 2 requests per second per token. Responses are cached server-side and refreshed the instant a code arrives, so polling every few seconds is fine.

Request

curl -X GET "https://getatext.com/api/record?token=YOUR_RECORD_TOKEN"

Responses

// Code received { "code": 1, "msg": "success", "data": { "code": "123456", "code_time": "2026-08-25 14:03:11", "expired_date": "2026-09-09 00:00:00" } } // Rental alive, no SMS yet { "code": 0, "msg": "No verification code", "data": { "code": "", "code_time": "", "expired_date": "2026-09-09 00:00:00" } } // Unknown token { "code": 0, "msg": "token does not exist", "data": { "code": "", "code_time": "", "expired_date": "" } }

The pair handed to end users

+13033597128|https://getatext.com/api/record?token=vybg8yaytl7m2d7p4alpiepx9dpeo5cuk783 // record_pair as returned by the rental endpoints; dates are US Eastern (America/New_York), // and only the extracted code is ever exposed, never the SMS text.

number_url_format — the number/expiry pair

A second pair on the same Code By URL enablement. Where record_pair gives the number and a polling URL, number_url_format gives the number and the moment the rental expires, so a panel that only needs to show its user how long the number lives does not have to parse a URL. It ships in the same creation and status responses as record_pair, and is null on accounts without Code By URL.

+14105370251|2026-10-05 17:01 // number_url_format: "+1" + the 10-digit number, then the expiry as // YYYY-MM-DD HH:MM in US Eastern (America/New_York).

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" }