API Documentation

Authentication

API integrations authenticate with your API key — include it in the Authorization header on every request. (The dashboard UI uses a separate logged-in session, so requests made from the browser are authenticated by your session cookie rather than an API key.)

The /api/v1/numbers/available and /api/v1/numbers/rent endpoints additionally accept a logged-in session cookie (dual auth) so they can be called from the dashboard UI as well as with an API key.

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

Get your API key from Settings → API Access

Phone Numbers

{
  "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"
    }
  ]
}

{
  "success": true,
  "numbers": [
    {
      "phone_number": "+13125551234",
      "region": "Chicago, IL",
      "region_type": "locality",
      "monthly_cost": 5.00,
      "upfront_cost": 0.00,
      "features": ["sms", "voice"]
    }
  ],
  "count": 20
}

{
  "success": true,
  "number": {
    "id": "uuid",
    "phone_number": "+13125551234",
    "label": "My Number",
    "status": "active",
    "rental_type": "reusable",
    "expires_at": "2026-02-15T10:30:00Z",
    "provider_id": "carrier-id",
    "service": { "id": "uuid", "name": "Telegram" }
  },
  "total_charged": 5.00,
  "credits_remaining": 12.20
}

Messages

{
  "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",
  "phone_number": "+13125558901",
  "from": "+15551234567",
  "body": "Your verification code is 847293",
  "received_at": "2024-01-15T10:30:00Z"
}

Webhooks are sent as HTTP POST requests with a Content-Type: application/json header. Your endpoint should return a 2xx status code to acknowledge receipt.

Rate Limits

Rate limits vary by endpoint. For authenticated requests, limits are keyed by user + IP. When you exceed a limit you'll receive a 429 response. Search and rent endpoints include a Retry-After header on 429 responses.

Error Handling

Error responses always include an error field. Depending on the endpoint, the body may also include hint, message, migrate_to, or credits_needed. The search (/api/v1/numbers/available) and rent (/api/v1/numbers/rent) endpoints additionally include a Retry-After header on their 429 responses.

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

HTTP Status Codes