# SMS.Red developer API reference

> Generated from the public developer-only OpenAPI contract. Narrative guides explain purchase recovery and current rental restrictions.

Contract SHA256: `113f84f447bdb0f50efed9999c3cc5a2b1ce42aac93cc89a9b616dc064b7872d`. Release date: 2026-10-05.

Base: `https://sms.red/api/v1/developer`; reseller keys use their own store origin. Authenticate with `X-API-Key` or `Authorization: Bearer`. IDs are returned by the catalog or order API. Durations are milliseconds; prices are USD decimal strings.

Purchases require a saved `Idempotency-Key` and `maxPrice`. Reconcile timeouts through purchase attempts. Rental `autoRenew`/`alwaysOn` creation options in the schema are currently rejected; auto-renew consent is dashboard-only. See [rentals](https://sms.red/docs/ai/rentals.md) and [retry handling](https://sms.red/docs/ai/errors-and-retries.md).

## Operations

### `GET /balance`

Get the balance of the account bound to this key

Response `200`: `DeveloperBalanceDto`.

### `GET /services`

Browse services and current account prices

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| page | query | no | number |  |
| pageSize | query | no | number |  |
| name | query | no | string |  |
| type | query | yes | string (otp, rent) |  |
| countryCode | query | no | string |  |
| inStock | query | no | boolean |  |

Response `200`: `GetListServicesDto`.

### `GET /services/{serviceId}/durations`

Get available terms, stock and exact purchase prices

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| serviceId | path | yes | string |  |
| countryCode | query | yes | string |  |
| providerId | query | no | string |  |
| kind | query | no | string (otp, rent) |  |

Response `200`: `GetListProviderServiceDurations`.

### `GET /verifications`

RetailDeveloperController_verifications

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| page | query | no | number |  |
| pageSize | query | no | number |  |
| view | query | no | string (active, history) | Active shows reserved orders; history shows completed, cancelled or expired orders. |
| number | query | no | string |  |
| status | query | no | string (reserved, successful, timeout, canceled, expired) |  |
| countryId | query | no | string |  |

Response `200`: `GetListVerificationsDto`.

### `POST /verifications`

Buy an OTP using an exact quote and an idempotency key

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| idempotency-key | header | yes | string |  |
| Idempotency-Key | header | yes | string | Reuse this key for retries of one purchase (8–128 letters, digits, underscores or hyphens). |

JSON body: `DeveloperCreateVerificationDto`.

Response `200`: `CreateOrderResult`.

### `GET /verifications/{id}`

RetailDeveloperController_verification

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |

Response `200`: `GetVerificationDto`.

### `GET /verifications/{id}/messages`

RetailDeveloperController_verificationMessages

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |
| page | query | no | number |  |
| pageSize | query | no | number |  |
| view | query | no | string (active, history) | Active shows reserved orders; history shows completed, cancelled or expired orders. |
| number | query | no | string |  |
| status | query | no | string (reserved, successful, timeout, canceled, expired) |  |
| countryId | query | no | string |  |

Response `200`: `GetListVerificationMessagesDto`.

### `POST /verifications/{id}/cancel`

RetailDeveloperController_cancelVerification

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |

Response `200`: empty body.

### `GET /rentals`

RetailDeveloperController_rentals

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| page | query | no | number |  |
| pageSize | query | no | number |  |
| view | query | no | string (active, history) | Active shows reserved orders; history shows completed, cancelled or expired orders. |
| number | query | no | string |  |
| status | query | no | string (reserved, successful, timeout, canceled, expired) |  |
| countryId | query | no | string |  |

Response `200`: `GetListRentalNumbersDto`.

### `POST /rentals`

RetailDeveloperController_rent

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| idempotency-key | header | yes | string |  |
| Idempotency-Key | header | yes | string |  |

JSON body: `DeveloperRentNumberDto`.

Response `200`: `CreateOrderResult`.

### `GET /rentals/{id}`

RetailDeveloperController_rental

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |

Response `200`: `GetRentalNumberDto`.

### `GET /rentals/{id}/messages`

RetailDeveloperController_rentalMessages

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |
| page | query | no | number |  |
| pageSize | query | no | number |  |
| view | query | no | string (active, history) | Active shows reserved orders; history shows completed, cancelled or expired orders. |
| number | query | no | string |  |
| status | query | no | string (reserved, successful, timeout, canceled, expired) |  |
| countryId | query | no | string |  |

Response `200`: `GetListRentalMessagesDto`.

### `POST /rentals/{id}/cancel`

RetailDeveloperController_cancelRental

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| id | path | yes | string |  |

Response `200`: empty body.

### `GET /purchase-attempts/{key}`

Inspect a purchase attempt after a timeout before issuing another purchase

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| key | path | yes | string |  |

Response `200`: `DeveloperPurchaseAttemptDto`.

## Schemas

### DeveloperBalanceDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| accountId | yes | string |  |
| balance | yes | string |  |
| currency | yes | string |  |

### GetServiceDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| name | yes | string |  |
| count | no | number |  |
| minPrice | no | string |  |
| maxPrice | no | string |  |
| income | no | string |  |
| status | yes | object |  |
| markupKind | yes | object |  |
| markupValue | yes | string \| null |  |
| isFavorite | no | boolean |  |
| code | yes | string |  |
| icon | yes | string \| null |  |
| type | yes | string |  |

### GetListServicesDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetServiceDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### GetProviderServiceDurationOptionDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| code | yes | string |  |
| price | yes | string |  |

### GetProviderServiceDurationDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| options | yes | array of GetProviderServiceDurationOptionDto |  |
| id | yes | string |  |
| duration | yes | number |  |
| human | yes | string |  |
| count | yes | number |  |
| price | yes | string |  |

### GetListProviderServiceDurations

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetProviderServiceDurationDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### OrderServiceDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| name | yes | string |  |
| count | no | number |  |
| minPrice | no | string |  |
| maxPrice | no | string |  |
| income | no | string |  |
| isFavorite | no | boolean |  |
| code | yes | string |  |
| icon | yes | string \| null |  |
| type | yes | string |  |

### OrderProviderDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| name | yes | string |  |

### GetCountryDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| code | yes | string |  |

### GetVerificationDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| number | yes | string |  |
| duration | yes | number |  |
| description | yes | string \| null |  |
| totalPrice | yes | string |  |
| code | yes | string \| null |  |
| sms | yes | string \| null |  |
| status | yes | string |  |
| isTransfering | yes | boolean |  |
| isCancelable | yes | boolean |  |
| service | yes | object \| null |  |
| provider | yes | OrderProviderDto |  |
| country | yes | GetCountryDto |  |
| expiresAt | yes | string |  |
| createdAt | yes | string |  |
| updatedAt | yes | string |  |

### GetListVerificationsDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetVerificationDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### DeveloperCreateVerificationDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| duration | yes | number | Duration in ms |
| serviceId | yes | string |  |
| countryCode | yes | string |  |
| providerId | no | string |  |
| description | no | string |  |
| maxPrice | yes | string | Maximum total charge in USD, taken from the terms quote |

### CreateOrderResult

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| number | yes | string |  |
| expiresAt | yes | string |  |
| createdAt | yes | string |  |

### GetVerificationMessageDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| text | yes | string |  |
| code | yes | string \| null |  |
| verification | yes | GetVerificationDto |  |
| createdAt | yes | string |  |

### GetListVerificationMessagesDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetVerificationMessageDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### GetRentalNumberDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| number | yes | string |  |
| duration | yes | number |  |
| description | yes | string \| null |  |
| totalPrice | yes | string |  |
| code | yes | string \| null |  |
| sms | yes | string \| null |  |
| status | yes | string |  |
| isTransfering | yes | boolean |  |
| isCancelable | yes | boolean |  |
| shouldRenew | yes | boolean |  |
| isAutoRenewEnabled | yes | boolean |  |
| canAutoRenew | yes | boolean | Whether this active rental supports wallet-funded auto-renew |
| service | yes | object \| null |  |
| provider | yes | OrderProviderDto |  |
| country | yes | GetCountryDto |  |
| expiresAt | yes | string |  |
| createdAt | yes | string |  |
| updatedAt | yes | string |  |

### GetListRentalNumbersDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetRentalNumberDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### DeveloperRentNumberDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| options | no | array of string (alwaysOn, autoRenew) |  |
| duration | yes | number | Duration in ms |
| serviceId | yes | string |  |
| countryCode | yes | string |  |
| providerId | no | string |  |
| description | no | string |  |
| maxPrice | yes | string | Maximum total charge in USD, taken from the terms quote |

### GetRentalMessageDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| id | yes | string |  |
| text | yes | string |  |
| code | yes | string \| null |  |
| rental | yes | GetRentalNumberDto |  |
| createdAt | yes | string |  |

### GetListRentalMessagesDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| items | yes | array of GetRentalMessageDto |  |
| page | yes | number |  |
| pageSize | yes | number |  |
| totalItems | yes | number |  |
| totalPages | yes | number |  |

### DeveloperPurchaseAttemptDto

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| key | yes | string |  |
| status | yes | string |  |
| activationId | yes | string \| null |  |
| recoveryState | yes | string \| null |  |
| error | yes | string \| null |  |
| createdAt | yes | string |  |

[Live OpenAPI JSON](https://sms.red/api/v1/developer/openapi.json) · [Interactive docs](https://sms.red/api/v1/developer/docs) · [Documentation index](https://sms.red/docs/ai/index.md)