WantSMS API Documentation

Getting Started

Base URL

All public API v1 endpoints are under this base URL:

https://wantsms.com/api/public/v1

Authentication

API key authentication

Create an API key in your dashboard and send it as a bearer token. Do not expose API keys in browser JavaScript.

Header

Authorization: Bearer wms_your_api_key

`X-API-Key` is accepted for simple clients, but do not send both authentication headers in the same request.

Errors

Response format

Success response

{
  "ok": true
}

Error response

{
  "ok": false,
  "error": "Missing or invalid API key."
}

400 Bad request

401 Missing or invalid API key

402 Insufficient credits

404 Not found

409 Already processed

422 Validation error

Durations

Allowed duration values

Reserve renewable rental

thirtyDay, ninetyDay, oneYear

Reserve standard rental

oneDay, threeDay, sevenDay, fourteenDay, thirtyDay, ninetyDay, oneYear

Extend standard rental

threeDay, sevenDay, fourteenDay, thirtyDay, ninetyDay, oneYear

US Area Codes

Optional area code selection

List available US area codes. Use q to search by area code or state, page to move through results, and limit to control how many area codes are returned per page.

GET /rentals/us/area-codes.php

Use the exact area_code value from this response when passing area_code to a renewable or standard reserve endpoint. area_code is optional. Exclude it if you do not want to select an area code.

Example response

{
  "ok": true,
  "country_iso": "US",
  "items": [
    {
      "area_code": "726",
      "state": "Texas"
    }
  ],
  "total": 317,
  "next_page": 2,
  "page": 1,
  "limit": 50
}

US Renewable Rentals

Renewable rental endpoints

GET /rentals/us/renewable/services.php

List available renewable rental services.

By default, this endpoint returns all available renewable service names with pagination. Use q to search services, page to move through results, and limit to control how many services are returned per page.

Use the exact name value from this response when calling the reserve endpoint.

GET /rentals/us/renewable/pricing.php

Get the current sell price for a US renewable rental before reserving a number.

Send values as query parameters. Required: service_name, duration, capability. Optional: area_code.

Allowed renewable durations: thirtyDay, ninetyDay, oneYear.

Example request

GET /rentals/us/renewable/pricing.php?service_name=airbnb&duration=thirtyDay&capability=sms

area_code is optional. Add it only if you want to price area-code selection.

Example response

{
  "ok": true,
  "category": "us_renewable",
  "service_name": "airbnb",
  "capability": "sms",
  "duration": "thirtyDay",
  "area_code": null,
  "sell_price_usd": "14.60",
  "currency": "USD"
}

POST /rentals/us/renewable/reserve.php

Reserve a US renewable rental number.

JSON request body

{
  "service_name": "airbnb",
  "duration": "thirtyDay",
  "capability": "sms",
  "area_code": "726"
}

area_code is optional. Exclude it if you do not want to select an area code.

POST /rentals/us/renewable/renew.php

Renew an active renewable rental.

When you reserve a rental, the response includes a unique WantSMS rental id. Use that id here to renew the rental.

Renewable rentals renew for the same duration used when the rental was first bought. For example, a thirtyDay rental renews for thirtyDay, and a ninetyDay rental renews for ninetyDay.

JSON request body

{
  "id": 456
}

US Standard Rentals

Standard rental endpoints

US standard rentals are non-renewable rentals.

GET /rentals/us/standard/services.php

List available standard rental services.

By default, this endpoint returns all available standard service names with pagination. Use q to search services, page to move through results, and limit to control how many services are returned per page.

Use the exact name value from this endpoint when calling the reserve endpoint.

GET /rentals/us/standard/pricing.php

Get the current sell price for a US standard rental before reserving a number.

Send values as query parameters. Required: service_name, duration, capability. Optional: area_code.

Allowed standard durations: oneDay, threeDay, sevenDay, fourteenDay, thirtyDay, ninetyDay, oneYear.

Example request

GET /rentals/us/standard/pricing.php?service_name=airbnb&duration=oneDay&capability=sms

area_code is optional. Add it only if you want to price area-code selection.

Example response

{
  "ok": true,
  "category": "us_standard",
  "service_name": "airbnb",
  "capability": "sms",
  "duration": "oneDay",
  "area_code": null,
  "sell_price_usd": "3.30",
  "currency": "USD"
}

POST /rentals/us/standard/reserve.php

Reserve a US standard rental number.

JSON request body

{
  "service_name": "airbnb",
  "duration": "thirtyDay",
  "capability": "sms",
  "area_code": "726"
}

area_code is optional. Exclude it if you do not want to select an area code.

POST /rentals/us/standard/extend.php

Extend an active standard rental.

When you reserve a rental, the response includes a unique WantSMS rental id. Use that id here to extend the rental.

JSON request body

{
  "id": 456,
  "extension_duration": "threeDay"
}

Shared US Rental Endpoints

Rental details and messages

GET /rentals/us/sms.php?id=456

Fetch latest SMS messages for a US rental. This endpoint works for both renewable and standard US rentals.

GET /rentals/us/rentals.php

Lists all US rentals that exist in your WantSMS account. Query: `page`, `limit`, `category`, `status`, `q`.

GET /rentals/us/rental.php?id=456

Get details for a single US rental by id.

POST /rentals/us/refund.php

Refund an eligible US rental inside its refund window.

You can self-refund up to 2 rentals within 30 minutes. Do not overuse refunds. Only rentals that have not received SMS are eligible for self-refund. For other refund requests, contact WantSMS support.

JSON request body

{
  "id": 456
}

Need Help?

API support

If you need help with integration or have questions regarding the API, contact WantSMS support.

Contact us