API Reference

The Acc-Gen API allows you to programmatically purchase SMS verification numbers, retrieve premium social media accounts, and check your account balance. All API access is over HTTPS, and data is sent and received as JSON.

Base URL

https://acc-gen.net/api/v1

Authentication

All API requests must include your API key in the X-API-Key header. You can generate your API key from your account settings.

Header

X-API-Key: acc_your_api_key_here

Response Format

All API responses are wrapped in a consistent envelope. Successful responses include a data object. Failed responses include an error object with a machine-readable code.

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or inactive API key.
RATE_LIMIT_EXCEEDED	429	Too many requests. Reduce your request rate.
VALIDATION_ERROR	400	Request body or params failed validation. See message for details.
INSUFFICIENT_BALANCE	402	Your account balance is too low to complete the order.
INSUFFICIENT_STOCK	503	No stock available for the requested item.
NOT_FOUND	404	The requested resource was not found.
INTERNAL_ERROR	500	An unexpected server error occurred.

User

Account-level information for the authenticated reseller.

GET/api/v1/user/balance

Returns the current balance in Naira (NGN) for the authenticated reseller account.

Examples

curl -X GET "https://acc-gen.net/api/v1/user/balance" \
  -H "X-API-Key: YOUR_API_KEY"

SMS Verification

Browse available services, check stock, and place orders for temporary SMS verification numbers. Orders expire after ~20 minutes.

GET/api/v1/sms/services

Returns the full list of SMS verification services and the countries they are available in. Each country entry includes its own price and stock status. The top-level price_ngn is the global minimum across all countries (useful for display sorting). Prices are in Naira (NGN).

Examples

curl -X GET "https://acc-gen.net/api/v1/sms/services" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/sms/stock

Check the available number count for a specific service and country combination. Prices are in Naira (NGN).

Parameters

Parameter	Type	Location	Required	Description
service_id	string	query	required	The SMS-Activate service code (e.g. "wa" for WhatsApp).
country_id	number	query	required	The SMS-Activate country ID (e.g. 187 for USA).

Examples

curl -X GET "https://acc-gen.net/api/v1/sms/stock?service_id=wa&country_id=187" \
  -H "X-API-Key: YOUR_API_KEY"

POST/api/v1/sms/orders

Place a new SMS verification order. Deducts balance in Naira and returns a phone number ready to receive an SMS code.

Parameters

Parameter	Type	Location	Required	Description
service_id	string	body	required	SMS-Activate service code (e.g. "wa" for WhatsApp, "tg" for Telegram).
country_id	number	body	required	SMS-Activate country ID (e.g. 187 for USA, 0 for Russia).

Examples

curl -X POST "https://acc-gen.net/api/v1/sms/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id": "wa", "country_id": 187}'

GET/api/v1/sms/orders/{id}

Get the current status and received SMS code for a specific order. Poll this endpoint until status is "completed".

Parameters

Parameter	Type	Location	Required	Description
id	string (UUID)	path	required	The UUID of the SMS order returned from Place Order.

Examples

curl -X GET "https://acc-gen.net/api/v1/sms/orders/931fbc26-be59-4d50-bab8-ac320a975cc4" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/sms/orders

List all SMS orders placed with this API key, with pagination. Orders are returned newest first.

Parameters

Parameter	Type	Location	Required	Description
limit	number	query	optional	Max results to return. Defaults to 20, max 100.
offset	number	query	optional	Number of results to skip for pagination.

Examples

curl -X GET "https://acc-gen.net/api/v1/sms/orders?limit=20&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

DELETE/api/v1/sms/orders/{id}

Cancel a pending or completed SMS order and receive a full refund to your balance. Only orders in "pending" or "completed" status can be cancelled.

Parameters

Parameter	Type	Location	Required	Description
id	string (UUID)	path	required	The UUID of the SMS order to cancel.

Examples

curl -X DELETE "https://acc-gen.net/api/v1/sms/orders/931fbc26-be59-4d50-bab8-ac320a975cc4" \
  -H "X-API-Key: YOUR_API_KEY"

Premium Accounts

Purchase pre-built social media accounts. Credentials are delivered immediately in the purchase response. All past orders with credentials are also retrievable via the list/get endpoints.

GET/api/v1/accounts/catalog

Returns the list of all available premium account types for purchase. Prices are in Naira (NGN).

Examples

curl -X GET "https://acc-gen.net/api/v1/accounts/catalog" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/accounts/catalog/{id}

Get full details for a single catalog item including stock and pricing. Price is in Naira (NGN).

Parameters

Parameter	Type	Location	Required	Description
id	number	path	required	The numeric ID of the account product.

Examples

curl -X GET "https://acc-gen.net/api/v1/accounts/catalog/15" \
  -H "X-API-Key: YOUR_API_KEY"

POST/api/v1/accounts/orders

Purchase one or more account instances. Deducts balance in Naira and returns login credentials immediately.

Parameters

Parameter	Type	Location	Required	Description
account_id	number	body	required	Numeric ID of the account product to purchase.
quantity	number	body	optional	How many to buy. Defaults to 1, max 50.

Examples

curl -X POST "https://acc-gen.net/api/v1/accounts/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 15, "quantity": 2}'

GET/api/v1/accounts/orders/{id}

Get full details of a specific account order, including the delivered credentials. Price is in Naira (NGN).

Parameters

Parameter	Type	Location	Required	Description
id	string (UUID)	path	required	The ID of the account order.

Examples

curl -X GET "https://acc-gen.net/api/v1/accounts/orders/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/accounts/orders

List all account orders placed with this API key. Credentials are included. Prices are in Naira (NGN).

Parameters

Parameter	Type	Location	Required	Description
limit	number	query	optional	Max results to return. Defaults to 20, max 100.
offset	number	query	optional	Number of results to skip for pagination.

Examples

curl -X GET "https://acc-gen.net/api/v1/accounts/orders?limit=20&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

SMS-Activate Stub

Drop-in compatible endpoint for SMS-Activate, HeroSMS, and DaisySMS clients. Point your bot or reseller tool at https://acc-gen.net/stubs/handler_api.php without changing any other code.

GET/stubs/handler_api.php

Drop-in SMS-Activate / HeroSMS compatible endpoint. Any bot or reseller tool that works with SMS-Activate can point its base URL here without code changes. All requests use GET or POST with api_key and action query parameters. Responses are plain text in SMS-Activate format.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	The action to perform (see individual endpoints below).

Examples

# Base URL for SMS-Activate compatible clients:
# https://acc-gen.net/stubs/handler_api.php

GET/stubs/handler_api.php?action=getBalance

Returns the current account balance in Naira (NGN). Compatible with both SMS-Activate and HeroSMS balance checks. This is the same balance as GET /api/v1/user/balance.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getBalance".

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"

GET/stubs/handler_api.php?action=getServicesList

Returns all available SMS services as a JSON object.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getServicesList".

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getServicesList"

GET/stubs/handler_api.php?action=getCountries

Returns all available countries as a JSON object keyed by SMS-Activate country ID.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getCountries".

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getCountries"

GET/stubs/handler_api.php?action=getPrices

Returns prices and stock counts in Naira (NGN), indexed by country ID then service code. Optionally filter by service or country.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getPrices".
service	string	query	optional	Filter by service code (e.g. "wa").
country	number	query	optional	Filter by country ID (e.g. 187).

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&service=wa&country=187"

GET/stubs/handler_api.php?action=getNumber

Purchase a phone number for SMS verification. Deducts balance and returns a short 8-character order ID and phone number.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getNumber".
service	string	query	required	Service code (e.g. "wa").
country	number	query	required	Country ID (e.g. 187 for USA).

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&country=187"

GET/stubs/handler_api.php?action=getStatus

Check the status of an activation. Poll this until STATUS_OK is returned with the SMS code.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getStatus".
id	string	query	required	The 8-character order ID from getNumber.

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=931fbc26"

GET/stubs/handler_api.php?action=setStatus

Update the status of an activation. Use status=8 to cancel (refunds balance), status=6 to confirm code received, status=3 to request another SMS.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "setStatus".
id	string	query	required	The 8-character order ID from getNumber.
status	number	query	required	1=SMS sent, 3=request another, 6=complete, 8=cancel.

Examples

# Cancel and refund:
curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=931fbc26&status=8"

# Confirm code received:
curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=931fbc26&status=6"

GET/stubs/handler_api.php?action=getActivations

Returns activation history for the account as an object keyed by short order ID. Equivalent to getHistory on HeroSMS.

Parameters

Parameter	Type	Location	Required	Description
api_key	string	query	required	Your Acc-Gen API key.
action	string	query	required	Must be "getActivations".
limit	number	query	optional	Max results to return. Defaults to 20, max 100.

Examples

curl "https://acc-gen.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getActivations&limit=20"

Webhooks

Configure a Webhook URL on your API key from the settings page. When an SMS code is received for one of your active orders, we will send a POST request to your server within seconds.

Note: Webhooks only fire for SMS orders. Premium Account credentials are delivered synchronously in the purchase response.

sms.received event

Fired when your SMS verification number receives a code. We POST this payload to your configured webhook URL.

POST to your webhook URL

{
  "event": "sms.received",
  "order_id": "your-order-uuid",
  "phone_number": "+14155552671",
  "sms_code": "123456",
  "full_sms_text": "Your verification code is 123456. Do not share it.",
  "received_at": "2026-03-06T14:05:00.000Z"
}