API Documentation

Integrate ReverbSMS into your applications with our REST API.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

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

Get your API key from Settings → API Access

Phone Numbers

GET/api/v1/numbers

List all your rented phone numbers.

Response

{
  "success": true,
  "numbers": [
    {
      "id": "uuid",
      "phone_number": "+13125558901",
      "label": "Main",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": "2024-02-15T10:30:00Z"
    }
  ]
}

GET/api/v1/numbers/available

Search for available phone numbers to rent.

Query Parameters

Parameter	Type	Description
country_code	string	Country code (default: US)
area_code	string	Filter by area code
state	string	Filter by state (e.g., IL, CA)
limit	number	Max results (default: 20)

Response

{
  "success": true,
  "numbers": [
    {
      "phone_number": "+13125551234",
      "region": "Chicago, IL",
      "monthly_cost": 5.00
    }
  ],
  "count": 20
}

POST/api/v1/numbers

Rent a new phone number.

Request Body

{
  "phone_number": "+13125551234",
  "plan_id": "uuid-of-plan",
  "label": "My Number"
}

Response

{
  "success": true,
  "number": {
    "id": "uuid",
    "phone_number": "+13125551234",
    "label": "My Number",
    "status": "active",
    "expires_at": "2024-02-15T10:30:00Z"
  }
}

Messages

GET/api/v1/messages

List messages received on your numbers.

Query Parameters

Parameter	Type	Description
phone_number_id	string	Filter by specific number
limit	number	Max results (default: 50)
offset	number	Pagination offset

Response

{
  "success": true,
  "messages": [
    {
      "id": "uuid",
      "from": "+15551234567",
      "to": "+13125558901",
      "to_label": "Main",
      "body": "Your code is 123456",
      "received_at": "2024-01-15T10:30:00Z",
      "forwarded": true
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Webhooks

Receive real-time notifications when SMS messages arrive. Configure your webhook URL in Settings.

Webhook Payload

{
  "event": "message.received",
  "data": {
    "id": "uuid",
    "phone_number": "+13125558901",
    "from": "+15551234567",
    "body": "Your verification code is 847293",
    "received_at": "2024-01-15T10:30:00Z"
  }
}

Rate Limits

API requests are limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 response.

Error Handling

All errors return a consistent JSON format:

{
  "error": "Error message",
  "hint": "How to fix it"
}

HTTP Status Codes

200Success

400Bad request / Invalid parameters

401Unauthorized / Invalid API key

402Payment required / Insufficient credits

404Resource not found

429Rate limit exceeded

500Server error