Public Client API v1

Client API

REST JSON endpoints for short-term SMS verification rentals, authenticated with user-generated SMSINBOX API keys.

Base URL

https://smsinbox.net/api/client/v1

Auth

Authorization: Bearer <api_key>

Scope

Short-term rentals only

Envelope

{ data, error } for every response

API Key

Client API requests use a user-generated key from your SMSINBOX account. Keep it private and send it asAuthorization: Bearer smsi_your_key on every request.

Open API Dashboard

Copy the new key

The full key is shown only once. Store it before closing the panel; later the dashboard only shows a masked key.

Rotate when needed

Each account has one active key. Generating a new key immediately revokes the current active key.

Where

Dashboard -> API Dashboard.

Active keys

One active key per account.

Regeneration

Generating a new key revokes the current active key.

Expiry

Optional. If set, expiry must be at least 30 days from now.

Revocation

Use Revoke in the API Dashboard if a key is no longer needed or may be exposed.

History

The dashboard records creation, last use, expiry, and revocation events.

Safe Retries

Send Idempotency-Key on POST requests that buy or replace a rental. If your first request reaches SMSINBOX but your client gets a timeout, retrying with the same key lets the API treat it as the same operation instead of creating a duplicate one.

Source

Client-generated, usually as a UUID. It is not your API key and it is not copied from the dashboard.

New operation

Use a new key for each new purchase or replacement attempt.

Retry after timeout

Reuse the same key with the same request body.

GET requests

Do not send it; GET requests do not create or replace rentals.

Limit

128 characters or fewer.

Example

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

Endpoints List

GET/catalog/services

List visible services available for short-term rentals.

GET/catalog/countries

List countries where a service currently has visible inventory.

GET/catalog/price

Get price options and optionally create a short-lived quote for purchase.

POST/rentals

Buy one or more short-term numbers.

GET/rentals

List the caller's short-term rentals.

GET/rentals/{id}

Get current stored status and details for one rental.

GET/rentals/{id}/sms

Read SMS code, text, all SMS messages, and rental status.

POST/rentals/{id}/cancel

Cancel an unused rental and refund when cancellation is still allowed.

POST/rentals/{id}/resend

Request another SMS for a rental after an SMS has already arrived.

POST/rentals/{id}/finish

Mark a rental finished after SMS has arrived.

POST/rentals/{id}/replace

Replace a still-unused active rental when replacement is allowed.

Method	Path	Purpose
GET	/catalog/services	List visible services available for short-term rentals.
GET	/catalog/countries	List countries where a service currently has visible inventory.
GET	/catalog/price	Get price options and optionally create a short-lived quote for purchase.
POST	/rentals	Buy one or more short-term numbers.
GET	/rentals	List the caller's short-term rentals.
GET	/rentals/{id}	Get current stored status and details for one rental.
GET	/rentals/{id}/sms	Read SMS code, text, all SMS messages, and rental status.
POST	/rentals/{id}/cancel	Cancel an unused rental and refund when cancellation is still allowed.
POST	/rentals/{id}/resend	Request another SMS for a rental after an SMS has already arrived.
POST	/rentals/{id}/finish	Mark a rental finished after SMS has arrived.
POST	/rentals/{id}/replace	Replace a still-unused active rental when replacement is allowed.

Endpoint Contracts

GET/catalog/services

List visible services available for short-term rentals.

Request

Auth

Authorization: Bearer smsi_your_key

Body

None.

Success Response

200 OK

Returns visible services with display name, minimum price in USD, and total available count.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

401 AUTH_UNAUTHORIZED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/catalog/services"

Response Example

{
  "data": [
    {
      "slug": "wa",
      "name": "WhatsApp",
      "min_price": 1.35,
      "total_count": 42
    }
  ],
  "error": null
}

GET/catalog/countries

List countries where a service currently has visible inventory.

Request

Auth

Authorization: Bearer smsi_your_key

Query

service_slug is required.

Body

None.

Success Response

200 OK

Returns countries for the requested service with minimum price in USD and total available count.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR401 AUTH_UNAUTHORIZED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/catalog/countries?service_slug=wa"

Response Example

{
  "data": [
    {
      "code": "16",
      "name": "United Kingdom",
      "min_price": 1.35,
      "total_count": 18
    }
  ],
  "error": null
}

GET/catalog/price

Get price options and optionally create a short-lived quote for purchase.

Request

Auth

Authorization: Bearer smsi_your_key

Query

service_slug and country_code are required.
quote=1 returns price_quote_id and quote_expires_at.

Body

None.

Success Response

200 OK

Returns current price options. Price fields are integer microcents unless a field is explicitly named min_price.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR400 RENTAL_OUT_OF_STOCK401 AUTH_UNAUTHORIZED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/catalog/price?service_slug=wa&country_code=16&quote=1"

Response Example

{
  "data": {
    "as_of": "2026-05-16T20:30:00.000Z",
    "is_stale": false,
    "rental_purchase_enabled": true,
    "price_quote_id": "00000000-0000-4000-8000-000000000000",
    "quote_expires_at": "2026-05-16T20:31:15.000Z",
    "default_price": {
      "charged_price": 1350000,
      "count": 18
    },
    "operators": [
      {
        "name": "any",
        "charged_price": 1350000,
        "count": 18
      }
    ],
    "rentals": [
      {
        "hours": 1,
        "charged_price": 1350000,
        "count": 18
      }
    ],
    "operator_rentals": {
      "any": [
        {
          "hours": 1,
          "charged_price": 1350000,
          "count": 18
        }
      ]
    },
    "offers": [
      {
        "charged_price": 1350000,
        "count": 18
      }
    ]
  },
  "error": null
}

POST/rentals

Buy one or more short-term numbers.

Request

Auth

Authorization: Bearer smsi_your_key

Headers

Content-Type: application/json
Idempotency-Key is optional and recommended for safe retries.

Body

service_slug and country_code are required.
quantity accepts 1..10 and defaults to 1.
duration_minutes accepts 20..720 and defaults to 20.
operator, max_price, and price_quote_id are optional.
max_price uses integer microcents.

Success Response

201 Created

Creates rentals and returns the purchased rental records plus the requested quantity.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR400 RENTAL_OUT_OF_STOCK401 AUTH_UNAUTHORIZED402 BALANCE_INSUFFICIENT403 FEATURE_DISABLED_BY_ADMIN409 PRICE_CHANGED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl -X POST "https://smsinbox.net/api/client/v1/rentals" \
  -H "Authorization: Bearer smsi_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "service_slug": "wa",
    "country_code": "16",
    "quantity": 1,
    "duration_minutes": 20,
    "price_quote_id": "00000000-0000-4000-8000-000000000000"
  }'

Response Example

{
  "data": {
    "rentals": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "phone_number": "+15551234567",
        "service_slug": "wa",
        "service_name": "WhatsApp",
        "country_code": "16",
        "country_name": "United Kingdom",
        "charged_price": 1350000,
        "status": "active",
        "sms_code": null,
        "sms_text": null,
        "sms_messages": [],
        "selected_operator": null,
        "selected_duration_min": 20,
        "selected_max_price": null,
        "replaced_from_rental_id": null,
        "can_cancel_after": "2026-05-16T20:35:00.000Z",
        "sms_resend_available_at": null,
        "expires_at": "2026-05-16T20:55:00.000Z",
        "created_at": "2026-05-16T20:30:00.000Z",
        "updated_at": "2026-05-16T20:30:00.000Z"
      }
    ],
    "quantity": 1
  },
  "error": null
}

GET/rentals

List the caller's short-term rentals.

Request

Auth

Authorization: Bearer smsi_your_key

Query

page defaults to 1.
page_size accepts 1..100 and defaults to 20.

Body

None.

Success Response

200 OK

Returns the caller's rentals with pagination metadata.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR401 AUTH_UNAUTHORIZED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals?page=1&page_size=20"

Response Example

{
  "data": {
    "rentals": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "phone_number": "+15551234567",
        "service_slug": "wa",
        "service_name": "WhatsApp",
        "country_code": "16",
        "country_name": "United Kingdom",
        "charged_price": 1350000,
        "status": "active",
        "sms_code": null,
        "sms_text": null,
        "sms_messages": [],
        "selected_operator": null,
        "selected_duration_min": 20,
        "selected_max_price": null,
        "replaced_from_rental_id": null,
        "can_cancel_after": "2026-05-16T20:35:00.000Z",
        "sms_resend_available_at": null,
        "expires_at": "2026-05-16T20:55:00.000Z",
        "created_at": "2026-05-16T20:30:00.000Z",
        "updated_at": "2026-05-16T20:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "error": null
}

GET/rentals/{id}

Get current stored status and details for one rental.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Body

None.

Success Response

200 OK

Returns one rental object with client-safe fields only.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR401 AUTH_UNAUTHORIZED404 RENTAL_NOT_FOUND429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000"

Response Example

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "phone_number": "+15551234567",
    "service_slug": "wa",
    "service_name": "WhatsApp",
    "country_code": "16",
    "country_name": "United Kingdom",
    "charged_price": 1350000,
    "status": "active",
    "sms_code": null,
    "sms_text": null,
    "sms_messages": [],
    "selected_operator": null,
    "selected_duration_min": 20,
    "selected_max_price": null,
    "replaced_from_rental_id": null,
    "can_cancel_after": "2026-05-16T20:35:00.000Z",
    "sms_resend_available_at": null,
    "expires_at": "2026-05-16T20:55:00.000Z",
    "created_at": "2026-05-16T20:30:00.000Z",
    "updated_at": "2026-05-16T20:30:00.000Z"
  },
  "error": null
}

GET/rentals/{id}/sms

Read SMS code, text, all SMS messages, and rental status.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Body

None.

Success Response

200 OK

Returns the latest SMS fields, all stored SMS messages, and the current rental status.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR401 AUTH_UNAUTHORIZED404 RENTAL_NOT_FOUND429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000/sms"

Response Example

{
  "data": {
    "sms_code": "123456",
    "sms_text": "Your verification code is 123456.",
    "sms_messages": [
      {
        "id": "sms_00000000-0000-4000-8000-000000000001",
        "code": "123456",
        "text": "Your verification code is 123456.",
        "received_at": "2026-05-16T20:38:00.000Z"
      }
    ],
    "status": "sms_received"
  },
  "error": null
}

POST/rentals/{id}/cancel

Cancel an unused rental and refund when cancellation is still allowed.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Body

None.

Success Response

200 OK

Confirms that the rental was cancelled and refunded.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR401 AUTH_UNAUTHORIZED403 RENTAL_CANCEL_LOCKED403 RENTAL_NOT_ACTIVE404 RENTAL_NOT_FOUND409 RENTAL_ACTION_UNAVAILABLE409 RENTAL_CANCEL_NOT_ALLOWED429 RATE_LIMITED502 RENTAL_CANCEL_FAILED

Request Example

curl -X POST \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000/cancel"

Response Example

{
  "data": {
    "message": "rental cancelled and refunded"
  },
  "error": null
}

POST/rentals/{id}/resend

Request another SMS for a rental after an SMS has already arrived.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Body

None.

Success Response

200 OK

Confirms the resend request and returns the next resend availability timestamp.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR400 RENTAL_NOT_ACTIVE401 AUTH_UNAUTHORIZED404 RENTAL_NOT_FOUND409 RENTAL_ACTION_UNAVAILABLE409 RENTAL_SMS_CODE_REQUIRED429 RENTAL_RESEND_LOCKED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl -X POST \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000/resend"

Response Example

{
  "data": {
    "message": "sms resend requested",
    "resend_available_at": "2026-05-16T20:40:00.000Z"
  },
  "error": null
}

POST/rentals/{id}/finish

Mark a rental finished after SMS has arrived.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Body

None.

Success Response

200 OK

Confirms that the rental was finished.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR400 RENTAL_NOT_ACTIVE401 AUTH_UNAUTHORIZED404 RENTAL_NOT_FOUND409 RENTAL_SMS_CODE_REQUIRED429 RATE_LIMITED500 INTERNAL_ERROR

Request Example

curl -X POST \
  -H "Authorization: Bearer smsi_your_key" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000/finish"

Response Example

{
  "data": {
    "message": "rental finished"
  },
  "error": null
}

POST/rentals/{id}/replace

Replace a still-unused active rental when replacement is allowed.

Request

Auth

Authorization: Bearer smsi_your_key

Path

id must be a rental UUID owned by the API key user.

Headers

Idempotency-Key is optional and recommended for safe retries.

Body

None.

Success Response

200 OK

Returns the newly purchased replacement rental.

Errors

Error responses use the same envelope with data set to null and an error code/message payload.

400 VALIDATION_ERROR400 RENTAL_OUT_OF_STOCK401 AUTH_UNAUTHORIZED403 FEATURE_DISABLED_BY_ADMIN404 RENTAL_NOT_FOUND409 RENTAL_ACTION_UNAVAILABLE409 RENTAL_REPLACE_NOT_ALLOWED429 RENTAL_REPLACE_LOCKED429 RATE_LIMITED500 RENTAL_REPLACE_FAILED502 RENTAL_REPLACE_FAILED

Request Example

curl -X POST \
  -H "Authorization: Bearer smsi_your_key" \
  -H "Idempotency-Key: 9b3a2c0d-6d7f-4a11-9c6a-2a4f1d9e5c21" \
  "https://smsinbox.net/api/client/v1/rentals/00000000-0000-4000-8000-000000000000/replace"

Response Example

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "phone_number": "+15557654321",
    "service_slug": "wa",
    "service_name": "WhatsApp",
    "country_code": "16",
    "country_name": "United Kingdom",
    "charged_price": 1350000,
    "status": "active",
    "sms_code": null,
    "sms_text": null,
    "sms_messages": [],
    "selected_operator": null,
    "selected_duration_min": 20,
    "selected_max_price": null,
    "replaced_from_rental_id": "00000000-0000-4000-8000-000000000000",
    "can_cancel_after": "2026-05-16T20:42:00.000Z",
    "sms_resend_available_at": null,
    "expires_at": "2026-05-16T21:02:00.000Z",
    "created_at": "2026-05-16T20:37:00.000Z",
    "updated_at": "2026-05-16T20:37:00.000Z"
  },
  "error": null
}