API Documentation

kiwiSMS REST API v1. Create an API key in your dashboard. Base URL: your site origin (e.g. https://your-domain.com). OpenAPI spec: /openapi.json.

Authentication

Send your API key on every request:

X-API-Key: lsms_xxxxxxxx_your_secret
# or
Authorization: Bearer lsms_xxxxxxxx_your_secret

Recommended flow

  1. GET /api/v1/services — pick a service with stock
  2. GET /api/v1/balance — check wallet
  3. POST /api/v1/rentals — rent number
  4. Poll GET /api/v1/rentals/{id} until codes is non-empty, or use webhooks
  5. POST .../done when finished

Endpoints

GET/api/v1/balance

Wallet balance (USD).

Response

{ "balance": 12.5, "currency": "USD" }
GET/api/v1/services?country=187

Services with live stock, price, multi-SMS flag. Optional country code (default 187 = US).

Response

{
  "countryCode": "187",
  "catalogMode": true,
  "count": 42,
  "services": [
    { "service": "go", "name": "Google", "price": "0.12", "count": 120, "multiSms": true }
  ]
}
GET/api/v1/rentals?sync=1

Active rentals (WAITING/RECEIVED). sync=0 skips provider sync (faster).

Response

{
  "count": 1,
  "rentals": [{
    "id": "clx...",
    "externalId": "12345",
    "phone": "+12025551234",
    "service": "go",
    "status": "RECEIVED",
    "codes": ["123456"],
    "otpCode": "123456",
    "secondsRemaining": 840,
    "active": true
  }]
}
GET/api/v1/rentals/{id}?sync=1

Poll one rental — same shape as list item. Syncs SMS from provider when still active.

POST/api/v1/rentals

Rent a number (20 min). Charges wallet. Send Idempotency-Key header for safe retries.

Request

Headers:
  Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "service": "go",
  "max_price": "0.50",
  "areas": "212,718",
  "carrier": "tmo",
  "country": "187"
}

Response

{
  "rental": {
    "id": "clx...",
    "externalId": "12345",
    "phone": "+12025551234",
    "service": "go",
    "serviceName": "Google",
    "price": 0.12,
    "status": "WAITING",
    "expiresAt": "2026-05-29T12:00:00.000Z"
  }
}
POST/api/v1/rentals/{id}/cancel

Cancel WAITING rental — refunds wallet.

POST/api/v1/rentals/{id}/done

Mark rental completed (release number on provider).

POST/api/v1/rentals/{id}/renew

Renew same number (new 20 min session). Requires previous rental with externalId.

Response

{ "rental": { "id": "...", "asleep": false, ... } }

Idempotency

For POST /api/v1/rentals and POST .../renew, send header Idempotency-Key: <uuid> (max 256 chars). Reusing the same key with the same body within 24 hours returns the original response instead of creating a second charge. Required for safe retries after network timeouts.

  • IDEMPOTENCY_IN_PROGRESS — 409, same key still processing
  • IDEMPOTENCY_KEY_REUSED — 422, same key but different request body

Errors

JSON body { error, code? }. Common codes:

  • INSUFFICIENT_BALANCE — 402
  • SERVICE_UNAVAILABLE — 404
  • RENTAL_NOT_FOUND — 404
  • CANCEL_NOT_ALLOWED — not WAITING

Rate limits

Per API key (default 100 requests/minute). HTTP 429 when exceeded.

Webhooks

Set webhook URL on your account or API key. On OTP received, POST JSON:

{
  "event": "sms.received",
  "rentalId": "clx...",
  "serviceCode": "go",
  "serviceName": "Google",
  "phone": "+12025551234",
  "otpCode": "123456",
  "smsText": "...",
  "receivedAt": "2026-05-29T12:00:00.000Z"
}

Header X-Webhook-Signature = HMAC SHA256 of body with your webhook secret.