Documentation

Developer documentation

Realistic request patterns for the GlobalSMS JSON API. Create an API key after signing in; do not use placeholders or share credentials.

Section 1

Authentication

Send `Authorization: Bearer YOUR_API_KEY` with every request. Keys are hashed server-side and the complete key is displayed only once after creation.

GET /api/v1/account

Section 2

API keys

Create, name, expire, and revoke keys from your account. Usage is recorded with endpoint, method, status, and timestamp.

POST /account/api

Section 3

Countries

Use ISO 3166-1 alpha-2 country codes such as US, GB, CA, DE, FR, IT, ES, NL, AU, or ZA.

GET /api/v1/numbers/search?country=US

Section 4

Search numbers

Filter available numbers by country, type, and rental duration. Results include price and currency from active pricing rules.

GET /api/v1/numbers/search?country=US&type=mobile&duration_days=30

Section 5

Rent number

Rent an available number atomically. The server checks account status, balance, availability, provider status, and pricing before charging the wallet.

POST /api/v1/numbers/{number_id}/rent
{"duration_days":30}

Section 6

Release number

Release an active rental. The provider number is released when supported and the local lifecycle enters cooldown before reuse.

POST /api/v1/numbers/{number_id}/release

Section 7

Retrieve messages

List inbound SMS belonging to your rentals or retrieve one message by ID. SMS retention settings automatically remove old content.

GET /api/v1/messages?limit=50

Section 8

Wallet

Inspect current balance and currency.

GET /api/v1/wallet

Section 9

Transactions

Review immutable wallet ledger entries with before and after balances.

GET /api/v1/transactions

Section 10

Webhooks

Provider webhooks are signature-verified server-side. Paystack payment events are verified before wallets are credited.

POST /api/public/webhooks/sms/{provider}

Section 11

Errors

Errors use JSON with code and message fields: 400 validation, 401 authentication, 403 authorization, 404 not found, 409 conflict, 422 validation, 429 rate limit, and 500 server error.

{"error":{"code":"INSUFFICIENT_FUNDS","message":"insufficient funds"}}

Section 12

Rate limits

API keys default to 60 requests per minute. Exceeding a limit returns HTTP 429 and is recorded in usage history.

{"error":{"code":"RATE_LIMITED","message":"Too many requests"}}