SMS APIs

Authentication Requirements (As Implemented)

• Every /api/sms/* endpoint requires cookie session or API key auth.
• POST JSON routes below also enforce Content-Type: application/json via requireJson.
• Global secondary-session middleware allowlists /api/sms, so secondary sessions and API-key sessions can call SMS endpoints.

Request and Response Examples

GET /api/sms/phones/search

Query parameters:

• q (substring)
• country

Success response (200):

{
  "phones": [
    {
      "number": "447700900123",
      "country": "GB",
      "range": "mobile",
      "countryInfo": {
        "iso": "GB",
        "flag": "\ud83c\uddec\ud83c\udde7",
        "callingCode": "+44",
        "formatted": "+44 7700 900123"
      }
    }
  ],
  "total": 1
}

GET /api/sms/phones

Success response (200):

{
  "phones": [
    {
      "number": "12025550123",
      "country": "US",
      "range": "mobile",
      "countryInfo": {
        "iso": "US",
        "flag": "\ud83c\uddfa\ud83c\uddf8",
        "callingCode": "+1",
        "formatted": "+1 202 555 0123"
      }
    }
  ],
  "totalAvailable": 200,
  "showing": 20,
  "countries": 15
}

GET /api/sms/my-phones

Success response (200):

[
  {
    "number": "12025550123",
    "country": "US",
    "range": "mobile",
    "reservedAt": "2026-03-10T00:00:00.000Z",
    "countryInfo": {
      "iso": "US",
      "flag": "\ud83c\uddfa\ud83c\uddf8",
      "callingCode": "+1",
      "formatted": "+1 202 555 0123"
    }
  }
]

POST /api/sms/reserve

Request headers:

• Content-Type: application/json (required)

Request body:

{ "number": "12025550123" }

Success responses:

{ "ok": true, "message": "Reserved" }

{ "ok": true, "message": "Already yours" }

Common failures:

• 400: { "error": "Phone number required" }
• 409: { "ok": false, "error": "Phone not available" }
• 429: max phones reached

POST /api/sms/unreserve

Request headers:

• Content-Type: application/json (required)

Request body:

{ "number": "12025550123" }

Success response (200):

{ "ok": true }

GET /api/sms/topranges

Success response (200):

[
  { "iso": "US", "flag": "\ud83c\uddfa\ud83c\uddf8" },
  { "iso": "GB", "flag": "\ud83c\uddec\ud83c\udde7" }
]

POST /api/sms/add-countries

Request headers:

• Content-Type: application/json (required)

Request body:

{ "countries": ["US", "GB", "DE"] }

Success response (200):

{ "ok": true, "message": "Request sent" }

GET /api/sms/feed

Success response (200):

[
  {
    "number": "12025550123",
    "text": "Your code is 1234",
    "date": "2026-03-10T00:00:00.000Z"
  }
]

GET /api/sms/history/:number

Success response (200):

[
  {
    "number": "12025550123",
    "text": "Your code is 1234",
    "date": "2026-03-10T00:00:00.000Z"
  }
]

GET /api/sms/full-history

Success response (200):

[
  {
    "number": "12025550123",
    "text": "Your code is 1234",
    "date": "2026-03-10T00:00:00.000Z"
  },
  {
    "number": "447700900123",
    "text": "Verification: 4567",
    "date": "2026-03-10T00:01:00.000Z"
  }
]

POST /api/sms/free-all

Request headers:

• Content-Type: application/json (required)

Request body:

{}

Success response (200):

{ "ok": true, "freedCount": 2 }