API Documentation

Authentication

All API requests require an API key. You can find your key on the Settings page.

Pass your API key using one of these methods:

Option 1: Authorization Header (recommended)

Authorization: Bearer YOUR_API_KEY

Option 2: Query Parameter

GET /api/v1/balance?api_key=YOUR_API_KEY

Base URL: https://receive-sms.com/api/v1

Rate Limits

API requests are limited to 60 requests per minute per API key.

Rate limit info is included in response headers:

• X-RateLimit-Limit — Maximum requests per minute
• X-RateLimit-Remaining — Remaining requests in current window

Exceeding the limit returns HTTP 429 Too Many Requests.

Get Balance

Returns your current account balance.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://receive-sms.com/api/v1/balance

Response

{
  "status": "success",
  "balance": 24.50
}

Get Countries & Prices

Returns all available countries with monthly and yearly prices.

Response

{
  "status": "success",
  "countries": [
    {
      "country_code": "US",
      "month_price": 9,
      "year_price": 54
    },
    {
      "country_code": "GB",
      "month_price": 9,
      "year_price": 54
    }
  ]
}

My Numbers

Returns all phone numbers currently rented by your account.

Response

{
  "status": "success",
  "numbers": [
    {
      "phone_number": "12025551234",
      "country_code": "US",
      "rented_at": "2025-03-01 10:00:00",
      "expiration_date": "2025-03-31 10:00:00",
      "plan": "monthly",
      "auto_renew": true,
      "message_count": 15,
      "last_sms_received_date": "2025-03-20 14:30:00"
    }
  ]
}

Available Numbers

Search for available phone numbers in a specific country.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://receive-sms.com/api/v1/numbers/available?country=US"

Response

{
  "status": "success",
  "numbers": [
    { "phone_number": "12025559876", "country_code": "US" },
    { "phone_number": "12025554321", "country_code": "US" }
  ]
}

Purchase Number

Rent a phone number. Provide duration plus either country (random number) or number (specific number from available).

Parameters

*Provide exactly one of country or number.

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -d "duration=month&country=US" \
  https://receive-sms.com/api/v1/numbers/purchase

Response

{
  "status": "success",
  "message": "Number purchased successfully.",
  "number": {
    "phone_number": "12025559876",
    "country_code": "US",
    "rented_at": "2025-03-24 12:00:00",
    "expiration_date": "2025-04-23 12:00:00",
    "plan": "monthly",
    "auto_renew": true,
    "price": 9
  },
  "remaining_balance": 21.50
}

Get SMS Messages

Retrieve SMS messages received on a specific number you own.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://receive-sms.com/api/v1/numbers/12025559876/sms"

Response

{
  "status": "success",
  "messages": [
    {
      "from": "Google",
      "to": "12025559876",
      "message": "Your verification code is 123456",
      "time": "2025-03-20 14:30:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total": 15,
    "per_page": 20,
    "last_page": 1
  }
}

Toggle Auto-Renew

Enable or disable auto-renew for a specific number you own.

Parameters

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -d "enabled=false" \
  https://receive-sms.com/api/v1/numbers/12025559876/auto-renew

Response

{
  "status": "success",
  "message": "Auto-renew disabled for 12025559876",
  "auto_renew": false
}

Webhook (SMS Notifications)

Configure a webhook URL in your Settings to receive real-time SMS notifications. When a message arrives on any of your numbers, we'll send a request to your URL.

Webhook Payload

Sent as POST form data to your webhook URL:

Example POST Payload

message=Your+code+is+123456&to=12025559876&from=Google&time=2025-03-20+14:30:00

Error Codes

All error responses include:

{
  "status": "error",
  "message": "Description of what went wrong"
}