Account / API / Documentation

API Documentation

Complete reference and clear explanations for each endpoint, including request samples, exact response structures, error codes, and field descriptions.

Back to API Keys

GET/api/v1/user/profile

User Profile & Balance

This endpoint allows authenticated users to fetch their account details, current vendor profile, and live wallet balances (including available balance and frozen funds).

Authentication Requirement: Requires a valid API key with an active status, a valid expiration date, and the balance scope enabled. Pass your key via the Authorization: Bearer <YOUR_API_KEY> header or the x-api-key custom header

# Request Example (cURL)terminal

curl "https://www.accnumbers.com/api/v1/user/profile" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "id": "69f6fef8-0246-447b-9da8-fe4300e2b61c",
  "email": "user@accnumbers.com",
  "vendor": "accnumbers",
  "default_forwarding_number": "",
  "balance": 15000,
  "rating": 100,
  "default_country": {
    "name": "nigeria",
    "iso": "ng",
    "prefix": "+234"
  },
  "default_operator": {
    "name": "any"
  },
  "frozen_balance": 0
}

Detailed Error Messages

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when neither the Authorization header nor the x-api-key header is provided or correctly formatted.

401 UnauthorizedInvalid Key

"Unauthorized: Invalid API key"

Triggered when the provided key token does not exist in the database records.

403 ForbiddenInactive Key

"API key is inactive (Status: revoked)"

Triggered if the API key status has been deactivated or revoked by an administrator or user.

403 ForbiddenExpired Key

"API key has expired"

Triggered if the specified key lifetime (expires_at timestamp) has elapsed.

403 ForbiddenScope Mismatch

"This API key lacks permission to access account details (balance scope is disabled)."

Triggered when the API key structure has the balance permission scope explicitly configured as false.

Response Field Descriptions

Field	Type	Description
id	String (UUID)	The unique system identifier tied to the user profile.
email	String	The registered email address associated with the user account.
vendor	String	The service provider platform identifier (`accnumbers`).
balance	Number	The current available cash balance in the user wallet.
frozen_balance	Number	Funds temporarily locked during live activations or pending actions.
rating	Number	The system rating score assigned to the user.
default_country	Object	Default regional configuration values containing name, iso code, and telephone prefix.
default_operator	Object	Default network operator preference setting.

GET/api/v1/user/payments

User Payments & Transactions

This endpoint allows authenticated users to fetch their transaction history (such as credits, debits, and refunds) with pagination support, formatted according to standard financial schemas.

Query Parameters (Optional):

limit: Number of records to return per page (default is 15).
offset: Number of records to skip for pagination (default is 0).

# Request Example (cURL)terminal

curl "https://www.accnumbers.com/api/v1/user/payments?limit=5&offset=0" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "Data": [
    {
      "ID": 42,
      "TypeName": "credit",
      "ProviderName": "paystack",
      "Amount": 5000,
      "Balance": 15000,
      "CreatedAt": "2026-08-23T07:40:34.510606+00:00"
    }
  ],
  "PaymentTypes": [
    { "Name": "credit" },
    { "Name": "debit" },
    { "Name": "refund" }
  ],
  "PaymentProviders": [
    { "Name": "paystack" },
    { "Name": "system" }
  ],
  "Total": 1
}

Detailed Error Messages

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when neither the Authorization header nor the x-api-key header is provided.

401 UnauthorizedInvalid Key

"Unauthorized: Invalid API key"

Triggered when the provided API key does not match any entry in the database records.

403 ForbiddenInactive Key

"API key is inactive (Status: revoked)"

Triggered if the API key status is marked as inactive or revoked.

403 ForbiddenExpired Key

"API key has expired"

Triggered if the key's expires_at timestamp has passed.

403 ForbiddenScope Mismatch

"This API key lacks permission to access transaction records (balance scope is disabled)."

Triggered when the key has the balance scope explicitly configured as false.

Response Field Descriptions

Field	Type	Description
Data	Array	List of individual user transactions.
Data.ID	Number	Unique database index identifier for the transaction record.
Data.TypeName	String	Classification type of transaction (`credit`, `debit`, or `refund`).
Data.ProviderName	String	Gateway provider or source channel (`paystack` or `system`).
Data.Amount	Number	The monetary transaction value amount.
Data.Balance	Number	The resulting account wallet balance right after this transaction occurred.
Data.CreatedAt	String (ISO 8601)	Timestamp indicating exactly when the transaction was processed.
PaymentTypes	Array	Supported payment/transaction type categories.
PaymentProviders	Array	Supported payment gateway handlers.
Total	Number	The total count of transactions matching the user query criteria.

GET/api/v1/user/orders

User Orders & Rentals

This endpoint allows authenticated users to retrieve their virtual phone number rentals and order histories with pagination support.

Authentication Requirement: Requires a valid API key with an active status, a valid expiration date, and the purchase scope enabled. Pass your key via the Authorization: Bearer <YOUR_API_KEY> header or the x-api-key custom header.

Query Parameters (Optional):

limit: Number of records to return per page (default is 15).
offset: Number of records to skip for pagination (default is 0).

# Request Example (cURL)terminal

curl "https://www.accnumbers.com/api/v1/user/orders?limit=5&offset=0" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "Data": [
    {
      "id": 1042,
      "phone": "+2348012345678",
      "operator": "any",
      "product": "tg",
      "price": 1500,
      "status": "PENDING",
      "expires": "2026-08-23T08:40:34.510606+00:00",
      "sms": [],
      "created_at": "2026-08-23T07:40:34.510606+00:00",
      "country": "nigeria"
    }
  ],
  "ProductNames": [],
  "Statuses": [],
  "Total": 1
}

Detailed Error Messages

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when neither the authorization header nor the custom API key header is provided.

401 UnauthorizedInvalid Key

"Unauthorized: Invalid API key"

Triggered when the provided API key token does not exist in the database.

403 ForbiddenInactive Key

"API key is inactive (Status: revoked)"

Triggered if the API key status has been deactivated or revoked.

403 ForbiddenExpired Key

"API key has expired"

Triggered if the key's expires_at timestamp has passed.

403 ForbiddenScope Mismatch

"This API key lacks permission to access order/rental records (purchase scope is disabled)."

Triggered when the key has the purchase scope explicitly configured as false.

Response Field Descriptions

Field	Type	Description
Data	Array	List of individual rental order records.
Data.id	Number	The unique numeric index identifier of the rental order.
Data.phone	String	The virtual phone number assigned to the rental.
Data.operator	String	The telecommunication network operator (e.g., `any`).
Data.product	String	The target service product code (maps to service).
Data.price	Number	The cost amount charged for the activation.
Data.status	String	The current lifecycle state of the rental (e.g., `PENDING`, `FINISHED`).
Data.expires	String (ISO 8601)	Timestamp indicating when the active rental session expires.
Data.sms	Array	List of incoming SMS verification messages received on the number.
Data.created_at	String (ISO 8601)	Timestamp indicating when the rental order was initiated.
Data.country	String	The target country code or name selected for the order.
Total	Number	The total count of orders matching the user query criteria.

GET/api/v1/guest/prices

Global Guest Prices Catalog

This public endpoint retrieves real-time pricing catalogs for virtual number activations and services. It automatically applies your database markup configurations and local currency conversions without requiring API key authentication.

Access Requirement: Publicly accessible. No API key or authorization header is required to query this endpoint.

Query Parameters (Optional):

country: Filter pricing data by a specific country name or code (e.g., england).
product: Filter pricing data by a specific application or service product code (e.g., facebook).

# Request Examples (cURL)terminal

# 1. Get All Prices Globally

curl "https://www.accnumbers.com/api/v1/guest/prices" \

-H "Accept: application/json"

# 2. Filter by Country Only

curl "https://www.accnumbers.com/api/v1/guest/prices?country=england" \

-H "Accept: application/json"

# 3. Filter by Product Only

curl "https://www.accnumbers.com/api/v1/guest/prices?product=facebook" \

-H "Accept: application/json"

# 4. Filter by Both Country and Product

curl "https://www.accnumbers.com/api/v1/guest/prices?country=england&product=facebook" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "england": {
    "facebook": {
      "any": {
        "cost": 1500,
        "count": 42,
        "rate": 1.0
      }
    }
  }
}

Error Messages

500 Internal ErrorMissing Env Key

"API key is missing in server environment variables."

Triggered when the backend server environment lacks the required upstream provider API configuration.

502 Bad GatewayParse Failure

"Failed to parse provider JSON payload."

Triggered if the upstream pricing provider returns a malformed or non-JSON response body.

Response Field Descriptions

Field	Type	Description
country_key	Object / Array	Top-level keys representing specific countries available for service.
product_key	Object / Array	Nested keys under each country representing application/service IDs (e.g., `facebook`, `tg`).
operator_name	Object	Network operator identifier mapping (e.g., `any`).
cost	Number	The final calculated cost converted to local currency(NGN).
count	Number	Available stock quantity of phone numbers for that category.
rate	Number	Upstream pricing multiplier or tier rating metric.

GET/api/v1/guest/products/{country}/{operator}

Guest Products Catalog by Country & Operator

This public endpoint retrieves real-time product stocks and dynamic activation prices for a specified country and network operator combination. It automatically applies your database markup configurations and local currency conversions without requiring API key authentication.

Access Requirement: Publicly accessible. No API key or authorization header is required to query this endpoint.

Path Parameters (Required):

country: The target country code or name (e.g., england).
operator: The target telecommunication network operator name (e.g., any).

# Request Example (cURL)terminal

curl "https://www.accnumbers.com/api/v1/guest/products/${country}/${operator}" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "facebook": {
    "Category": "activation",
    "Qty": 42,
    "Price": 1500
  }
}

Error Messages

400 Bad RequestMissing Params

"Missing country or operator path parameters."

Triggered when either the country or operator segment is omitted from the request route path.

500 Internal ErrorMissing Env Key

"API key is missing in server environment variables."

Triggered when the backend server environment lacks the required upstream provider API configuration.

502 Bad GatewayParse Failure

"Failed to parse provider JSON payload."

Triggered if the upstream pricing provider returns a malformed or non-JSON response body.

Response Field Descriptions

Field	Type	Description
product_name	String (Key)	The unique identification key of the target service product (e.g., `facebook`, `tg`).
Category	String	The classification category type of the activation product (e.g., `activation`).
Qty	Number	The available real-time active stock count of numbers for the service.
Price	Number	The final converted local price calculated with your custom database markup rules applied.

GET/api/v1/user/buy/activation/{country}/{operator}/{product}

User Buy Activation

This endpoint allows authenticated users to purchase a virtual phone number activation for a specific country, operator, and service product. It automatically checks user wallet balances, deducts the funds, logs the transaction, sends an in-app notification, and registers the order.

Path Parameters (Required):

country: Target country name or code in lowercase (e.g., canada).
operator: Specific mobile network operator name or wildcard any (e.g., any).
product: Target service or application name in lowercase (e.g., tiktok).

# Request Example (cURL)terminal

curl -X GET "https://www.accnumbers.com/api/v1/user/buy/activation/canada/any/tiktok" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "id": 1084665247,
  "phone": "+18258520792",
  "operator": "any",
  "product": "tiktok",
  "price": 123,
  "status": "PENDING",
  "expires": "2026-09-04T11:18:34.109447399Z",
  "sms": [],
  "created_at": "2026-09-04T10:58:34.623918+00:00",
  "country": "canada"
}

Detailed Error Messages

400 Bad RequestMissing Params

"Missing country, operator, or product path parameters."

Triggered when any required path segment is missing from the request URL.

400 Bad RequestInsufficient Funds

"Insufficient wallet balance to complete this purchase."

Triggered when the user wallet balance is less than the calculated price of the activation product.

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when no valid authorization header or token is provided.

403 ForbiddenScope Mismatch

"This API key lacks permission to purchase numbers (purchase scope is disabled)."

Triggered when the key has the purchase scope explicitly disabled.

502 Bad GatewayProvider Error

"Upstream provider failed to fulfill the purchase order."

Triggered when the external activation provider encounters an error or returns a failure response during fulfillment.

Response Field Descriptions

Field	Type	Description
id	Number	The unique upstream order identification number.
phone	String	The virtual phone number assigned for activation.
operator	String	The network operator selected or resolved for the order.
product	String	The target product or application code (e.g., `tiktok`).
price	Number	The final cost deducted from the user wallet.
status	String	The order status state (e.g., `PENDING`).
expires	String (ISO 8601)	Timestamp indicating when the activation window expires.
sms	Array	List of incoming SMS messages received for the activation.
created_at	String (ISO 8601)	Timestamp indicating when the order was created.
country	String	The country selected for the activation order.

GET/api/v1/user/check/{id}

User Check Order Status

This endpoint allows authenticated users to check and retrieve the complete order details and current lifecycle status of an active virtual number rental order using a path parameter.

Path Parameters (Required):

id: The unique numeric order ID of the active rental (e.g., 106968055).

# Request Example (cURL)terminal

curl -L -X GET "https://www.accnumbers.com/api/v1/user/check/106968055" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "id": 106968055,
  "created_at": "2026-08-13T10:10:35.43421+00:00",
  "phone": "+15306109780",
  "product": "whatsapp",
  "price": 3467,
  "status": "FINISHED",
  "expires": "2026-08-13T10:30:35.14971+00:00",
  "sms": [
    {
      "code": "650358",
      "date": "2026-08-13T10:10:52.588935Z",
      "text": "<#>YourWhatsAppcode:650358Don'tsharethiscodewithothers4sgLq1p5sV6",
      "sender": "12403486504",
      "created_at": "2026-08-13T10:10:52.623214Z"
    }
  ],
  "forwarding": false,
  "forwarding_number": "",
  "country": "usa"
}

Detailed Error Messages

404 Not FoundOrder Missing

"Order record not found or does not belong to user."

Triggered when the specified order ID does not match any active records in database storage.

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when no valid authorization header or token is provided.

403 ForbiddenScope Mismatch

"This API key lacks permission to manage orders (purchase scope is disabled)."

Triggered when the key has the purchase scope explicitly disabled.

Response Field Descriptions

Field	Type	Description
id	Integer	The unique numeric order ID.
created_at	String	Timestamp when the order was created.
phone	String	The assigned virtual phone number.
product	String	The target application or service name (e.g., whatsapp).
price	Integer	The cost associated with the rental order.
status	String	The current state response of the order (`FINISHED`, etc.).
expires	String	Timestamp when the order rental expires.
sms	Array	List of received SMS messages, containing codes, dates, sender info, and text payload.
forwarding	Boolean	Indicates if call or SMS forwarding is active.
forwarding_number	String	The phone number used for forwarding, if enabled.
country	String	The country code or name for the number origin.

GET/api/v1/user/finish/{id}

User Finish Order

This endpoint allows authenticated users to mark an active virtual number rental order as finished using a path parameter.

Path Parameters (Required):

id: The unique numeric order ID of the rental to finish (e.g., 11631253).

# Request Example (cURL)terminal

curl -L -X GET "https://www.accnumbers.com/api/v1/user/finish/11631253" \

-H "Authorization: Bearer acc_test_6ede12ca9a8ab629ab207f5346140cea" \

-H "Accept: application/json"

# Success Response (200 OK)

{
  "id": 11631253,
  "created_at": "2018-10-13T08:13:38.809469028Z",
  "phone": "+447350690992",
  "product": "facebook",
  "price": 21,
  "status": "FINISHED",
  "expires": "2018-10-13T08:28:38.809469028Z",
  "sms": [
    {
      "created_at": "2018-10-13T08:20:38.809469028Z",
      "date": "2018-10-13T08:19:38Z",
      "sender": "Facebook",
      "text": "Facebook: 09363 - use this code to reclaim your suspended profile.",
      "code": "09363"
    }
  ],
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

Detailed Error Messages

404 Not FoundOrder Missing

"Order record not found or does not belong to user."

Triggered when the specified order ID does not match any active records in database storage.

401 UnauthorizedMissing Token

"Missing or invalid API token"

Triggered when no valid authorization header or token is provided.

403 ForbiddenScope Mismatch

"This API key lacks permission to manage orders (purchase scope is disabled)."

Triggered when the key has the purchase scope explicitly disabled.

Response Field Descriptions

Field	Type	Description
id	Integer	The unique numeric order ID.
created_at	String	Timestamp when the order was created.
phone	String	The assigned virtual phone number.
product	String	The target application or service name (e.g., facebook).
price	Integer	The cost associated with the rental order.
status	String	The updated state response of the order (`FINISHED`).
expires	String	Timestamp when the order rental expires.
sms	Array	List of received SMS messages, containing codes, dates, sender info, and text payload.
forwarding	Boolean	Indicates if call or SMS forwarding is active.
forwarding_number	String	The phone number used for forwarding, if enabled.
country	String	The country code or name for the number origin.