SMSPalm Verification API

1. Overview

SMSPalm provides verification-number APIs for virtual number providers. Typical flow: getNumber -> getStatus polling -> setStatus to complete/cancel.

Provider selection: use server=serverone (default, PalmServerOne), server=servertwo (PalmServerTwo), or server=serverthree (PalmServerThree).

1. Fetch services and prices for a country.
2. Reserve a number for a service.
3. Poll for SMS code.
4. Finalize or cancel activation.

2. Authentication

Every request includes your API key in an HTTP header. API keys in URLs are rejected because URLs are commonly retained in access logs and browser history.

Get your API key from your SMSPalm account dashboard: Settings -> API Key (open settings).

curl -H "X-API-Key: YOUR_API_KEY" "https://smspalm.com/api/v1/handler?action=getBalance"

Rate limit: 100 requests/min per token. Contact support if you need higher limits.

3. Get Balance

action=getBalance

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getBalance"

Response

ACCESS_BALANCE:124.94

4. Get Countries

action=getCountries

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getCountries"

Default provider is PalmServerOne. To use PalmServerTwo, add server=servertwo. To use PalmServerThree, add server=serverthree.

Response (JSON array)

[
  {"id": 187, "eng": "United States"},
  {"id": 50, "eng": "Bangladesh"}
]

5. Get Services List

action=getServicesList

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getServicesList"

Response (JSON)

{
  "status": "success",
  "services": [
    {"code": "wa", "name": "WhatsApp"},
    {"code": "tg", "name": "Telegram"}
  ]
}

Service identifier returned by the API is code (also used as short_name in SMSPalm integration logic). Use this value in getNumber&service=....

6. Get Prices

action=getPrices

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getPrices" \
  --data-urlencode "service=wa" \
  --data-urlencode "country=US"

Response shape (JSON)

{
  "187": {
    "wa": {"cost": 250.00, "count": 345}
  }
}

Prices returned by the API are in Naira (NGN), same as frontend display.

7. Get Number

action=getNumber reserves a phone number for verification.

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getNumber" \
  --data-urlencode "service=wa" \
  --data-urlencode "country=US"

Wallet balance is checked before the system reserves/buys a number. If you don’t have enough balance, you’ll get NO_BALANCE.

To use PalmServerTwo instead of the default PalmServerOne route: add server=servertwo and pass an ISO country code like US. To use PalmServerThree: add server=serverthree and (optionally) pass a numeric country ID like 187.

Success Response

ACCESS_NUMBER:50292409:14804343809

Format: ACCESS_NUMBER:{activation_id}:{phone_number}

8. Get Status

action=getStatus&id={activation_id}

SMSPalm always routes status and cancellation requests by the order's stored provider; a caller-supplied server value cannot override it.

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=getStatus" \
  --data-urlencode "id=50292409"

Possible Responses

9. Set Status

action=setStatus&id={activation_id}&status={code}

If server is not provided, SMSPalm will automatically route the request based on the stored order provider. For PalmServerTwo, only status=8 (cancel) is supported via this endpoint.

Status Codes

Example

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=setStatus" \
  --data-urlencode "id=50292409" \
  --data-urlencode "status=8"

Possible Responses

ACCESS_READY
ACCESS_RETRY_GET
ACCESS_ACTIVATION
ACCESS_CANCEL

10. Cancel Order Endpoint

Cancel an active order by calling setStatus with status 8.

curl -G "https://smspalm.com/api/v1/handler" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "action=setStatus" \
  --data-urlencode "id=50292409" \
  --data-urlencode "status=8"

Response

ACCESS_CANCEL

11. Error Responses

Common provider error strings:

Use string-response parsing in your client because some actions do not return JSON.

12. Support & Contact

Postman Collection: Download JSON

Developer Email: support@smspalm.com