AgoVerify

Authentication

All API requests (except /health) must include your API key. You can create and manage keys from your Developer page in your dashboard.

X-API-Key: av_your_api_key_here

Or use the standard Bearer token header:

Authorization: Bearer av_your_api_key_here

API Key Permissions

Permission	Description
`full`	Read and write access (default). Can create orders, cancel, refill, resend, and reactivate.
`read_only`	Read-only. Cannot create orders, cancel, refill, resend, or reactivate.

Write operations are marked with a POST badge below and require a full key.

Base URL

https://agoverify.com/api/v1

Rate Limiting

Rate limits are applied per API key. Response headers indicate your current usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window

When rate limited, you receive a 429 Too Many Requests response with a retry_after field indicating when to retry.

Endpoints

Health & Account

GET /health

Check if the API is operational. No authentication required.

GET /balance

Get current account balance and currency.

SMS Activations

GET /sms/services

List all SMS verification services available via the API.

GET /sms/countries?service={code}

List available countries. Optionally filter by service code.

GET /sms/price?service={code}&country={code}

Get pricing for a service/country combination.

POST /sms/orders

Rent a phone number. Body: service_code, country_code, operator (optional). Requires full key.

GET /sms/orders

List SMS orders with pagination. Query: status, service, country, per_page.

GET /sms/orders/active

List all currently active SMS orders.

GET /sms/orders/{id}

Get details for a specific SMS order.

GET /sms/orders/{id}/status

Check order status and retrieve SMS code (polls upstream provider).

POST /sms/orders/{id}/cancel

Cancel an active order and refund balance. Requires full key.

POST /sms/orders/{id}/resend

Request the provider to resend the SMS. Requires full key.

POST /sms/orders/{id}/reactivate

Reactivate a completed number to receive a new SMS (charges balance). Requires full key.

Unified Backend

AgoVerify uses a unified backend. The system automatically selects the best available provider for each service and country based on admin-configured priority - you only ever request a service code and country code, and the platform handles the rest. No provider or server parameter is required or accepted.

Create an SMS order example

curl -X POST "https://agoverify.com/api/v1/sms/orders" \
  -H "X-API-Key: av_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service_code": "wa", "country_code": "0"}'

Webhooks

Webhooks are sent as POST requests to your registered endpoints. Configure them via the Developer page in your dashboard.

SMS Events

sms.order.created - a new SMS order was created.
sms.received - an SMS code was received for an order.
sms.order.cancelled - an order was cancelled and refunded.
sms.order.expired - an order expired and was refunded.

Each webhook includes a X-Webhook-Signature header (HMAC-SHA256 of the JSON body using your endpoint secret) and X-Webhook-Event header with the event name.

Typical Workflow

SMS Verification

GET /sms/services - find the service you need (e.g., wa for WhatsApp)
GET /sms/countries?service=wa - get available countries
GET /sms/price?service=wa&country=0 - check pricing
POST /sms/orders - create the order, receive phone number
Use the phone number on the target service
GET /sms/orders/{id}/status - poll for SMS code (or wait for webhook)
POST /sms/orders/{id}/cancel - cancel if no longer needed (get refund)

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "message": "Human-readable error message",
  "data": {}
}

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request
`401`	Unauthorized (invalid/missing API key)
`402`	Payment required (insufficient balance)
`403`	Forbidden (read-only key attempting write)
`404`	Not found
`422`	Validation error
`429`	Rate limit exceeded
`500`	Internal server error
`503`	Service unavailable (provider error)

AgoVerify API Documentation