# 1001SMS Reseller API

> 1001SMS is a reseller API for three products on one balance: SMS activations (a number for one verification code), virtual numbers (a number rented for 12 hours to a year, with an inbox), and eSIM data plans (activation code and QR delivered by API). Every endpoint takes an API key as `Authorization: Bearer <key>`, answers `{ "success": true, "data": ... }` or `{ "success": false, "error": "..." }`, and each key can have a signed webhook so events are pushed instead of polled.

Base URL: `https://www.1001sms.com/api/v1`. API version 2.0.0. Human docs: https://www.1001sms.com/api-docs. OpenAPI JSON: https://www.1001sms.com/api/v1/docs. Full reference for language models: https://www.1001sms.com/api-docs/llms-full.txt.

Authentication: `Authorization: Bearer YOUR_API_KEY` (or `?apiKey=`). Keys carry scopes: `read`, `activate`, `numbers`, `esim`. A call outside the key's scopes answers 403. Rate limit: 60 requests per minute per key. Money: every purchase is charged to the account balance at the live retail price; 402 means the balance is short and the response carries `required`.

Vocabulary: virtual-number countries are ISO codes (`GB`), terms are `12h 1d 7d 30d 180d 365d` (dedicated numbers: the last four), number types are `unlimited` (every service) or `service` (one service, pass its id from /numbers/pricing). eSIM plans are `per_day` (pass `days`) or `bundle`. Activation providers are named only by alias: EXTRA, MAIN, EXTRA 2, NEW.

## Lookup

Countries, services and activation prices. Read-only. https://www.1001sms.com/api-docs#lookup

- [GET /informative/services](https://www.1001sms.com/api-docs#services): Available services. Active services (apps/platforms) available for verification. Use the slug as the service value in pricing and order calls.
- [GET /informative/countries](https://www.1001sms.com/api-docs#countries): Available countries. Active countries where activation numbers are sold. Use the code or slug in pricing and order calls.
- [GET /informative/pricing](https://www.1001sms.com/api-docs#pricing-country): Prices by country. Pass country only to get every service and operator available in that country.
- [GET /informative/pricing](https://www.1001sms.com/api-docs#pricing-service): Prices by service. Pass service only to get every country and operator for that service.
- [GET /informative/pricing](https://www.1001sms.com/api-docs#pricing-service-country): Prices by service and country. Pass both to get the exact operator list for one market pair.

## Activations

Buy a number for one verification, read the SMS, cancel. Requires the activate scope. https://www.1001sms.com/api-docs#activations

- [POST /activations/order](https://www.1001sms.com/api-docs#order): Order an activation number. Places a new activation order and returns the rented number. The balance is charged immediately and refunded automatically when the provider fails.
- [POST /activations/check](https://www.1001sms.com/api-docs#check): Check for SMS. Asks the provider for new SMS, stores them and returns the current state. When the order timed out with no SMS it is refunded here.
- [GET /activations/{orderId}](https://www.1001sms.com/api-docs#get-order): Get one order. Full order details with every stored message.
- [GET /activations/active](https://www.1001sms.com/api-docs#active-orders): Active orders. Paginated orders with status RENTED, ACTIVE or PENDING, each with its latest message.
- [GET /activations/history](https://www.1001sms.com/api-docs#history): Order history. Paginated order history with optional status and date filters.
- [POST /activations/cancel](https://www.1001sms.com/api-docs#cancel): Cancel an order. Cancels one order. A full refund is given only when no real SMS was received.
- [POST /activations/cancel-all](https://www.1001sms.com/api-docs#cancel-all): Cancel every active order. Attempts to cancel every order with status RENTED, ACTIVE or PENDING and reports each outcome.
- [GET /activations/archive-all](https://www.1001sms.com/api-docs#archive): Finished orders. Lists terminal orders: EXPIRED, REFUNDED and BLOCKED.

## Virtual Numbers

Rent a number for days or months, read its inbox, renew, cancel. Requires the numbers scope. https://www.1001sms.com/api-docs#numbers

- [GET /numbers/countries](https://www.1001sms.com/api-docs#numbers-countries): Countries with virtual numbers. The countries where virtual numbers are sold, with the dial code and the number types available.
- [GET /numbers/pricing](https://www.1001sms.com/api-docs#numbers-pricing): Prices for one country. Everything sold in a country at today's price: the unlimited terms and, per dedicated service, its terms. `service` values are what you pass to /numbers/order.
- [GET /numbers/availability](https://www.1001sms.com/api-docs#numbers-availability): Stock for a term. How many unlimited numbers are in stock for one country and term right now.
- [POST /numbers/order](https://www.1001sms.com/api-docs#numbers-order): Rent a virtual number. Rents a number from the balance at the live price and returns it. Unlimited numbers may carry a nickname and auto-renew; dedicated ones need a service.
- [GET /numbers](https://www.1001sms.com/api-docs#numbers-list): Your virtual numbers. Your virtual numbers, newest first, with a message count each.
- [GET /numbers/{id}](https://www.1001sms.com/api-docs#numbers-get): One virtual number. One number with every stored message, newest first. `status` is ACTIVE, EXPIRED, REFUNDED or PENDING.
- [GET /numbers/{id}/messages](https://www.1001sms.com/api-docs#numbers-messages): The inbox. Asks the provider for anything new, stores it and returns every message, newest first. `fetched` is false when the provider did not answer; you then get what was already stored.
- [GET /numbers/{id}/renew](https://www.1001sms.com/api-docs#numbers-renew-options): Renewal options. The terms this number can be renewed for, at today's price. A dedicated number renews at its service's own tariff.
- [POST /numbers/{id}/renew](https://www.1001sms.com/api-docs#numbers-renew): Renew a number. Charges the balance and extends the number by one term from its current expiry. `autoRenew` may be changed at the same time (unlimited numbers).
- [POST /numbers/{id}/cancel](https://www.1001sms.com/api-docs#numbers-cancel): Cancel a number. Hands an unlimited number back and refunds it. Only within 120 minutes of purchase and only if no SMS arrived. Dedicated numbers cannot be cancelled.
- [PATCH /numbers/{id}](https://www.1001sms.com/api-docs#numbers-patch): Change auto-renew or nickname. Unlimited numbers only. Switch auto-renew on or off, or set a nickname (empty string clears it).

## eSIMs

Browse data plans, buy them, read the activation code and usage. Requires the esim scope. https://www.1001sms.com/api-docs#esims

- [GET /esims/destinations](https://www.1001sms.com/api-docs#esims-destinations): Destinations. Every destination with sellable plans: a country (ISO code), a region (comma-separated member codes) or a global plan.
- [GET /esims/packages](https://www.1001sms.com/api-docs#esims-packages): Plans for a destination. The plans sold for one destination at retail. `pricingUnit` is per_day (price is a daily rate, pass `days` when ordering) or bundle (one price for `durationDays`). `unlimited` is true for a plan with no cap and for a day pass that keeps working at `fupPolicy` after its daily allowance of `volumeBytes`, which is how we sell it.
- [GET /esims/packages/{packageCode}](https://www.1001sms.com/api-docs#esims-package): One plan. One plan by its code.
- [POST /esims/quote](https://www.1001sms.com/api-docs#esims-quote): Price an order. What an order would cost without placing it. Day passes can get a longer-trip discount, and orders of several eSIMs a multi-eSIM discount off the whole order; the rates are set by us and may change, so read them from this quote rather than hard-coding them.
- [POST /esims/order](https://www.1001sms.com/api-docs#esims-order): Buy an eSIM. Buys the plan from the balance and returns the order. `ready: true` means the profiles carry an activation code; otherwise poll GET /esims/orders/{id} or wait for the esim.allocated webhook. A provider failure refunds the balance and returns 502.
- [GET /esims/orders](https://www.1001sms.com/api-docs#esims-orders): Your eSIM orders. Your orders, newest first, each with its profiles. `packageName` is what the order was sold as ("Spain Unlimited · 7 days"); `packageCode` identifies the plan. `days` is the term of a day pass (null for a bundle). For an `unlimited` order a profile's `totalVolume` is the daily full-speed allowance, not a cap: show the order as unlimited and `usedVolume` as data used.
- [GET /esims/orders/{id}](https://www.1001sms.com/api-docs#esims-order-get): One order. One order with its profiles. While nothing is allocated yet the provider is asked again before answering. `refresh=1` also refreshes the data counters and status of each profile. `lifecycle` is preparing, ready, active, expired, failed, cancelled or refunded.

## Webhooks

Manage the calling key's webhook: URL, events, secret, test, deliveries. No scope needed. https://www.1001sms.com/api-docs#webhooks

- [GET /webhooks/config](https://www.1001sms.com/api-docs#webhooks-config-get): This key's webhook. The URL, the subscribed events, a hint of the secret and whether the endpoint is active or disabled.
- [PUT /webhooks/config](https://www.1001sms.com/api-docs#webhooks-config-put): Set the webhook. Sets the URL and events. Saving a URL clears the failure state and re-enables a disabled endpoint; the first save returns the signing `secret` once. `url: null` removes the webhook.
- [POST /webhooks/config/rotate-secret](https://www.1001sms.com/api-docs#webhooks-rotate): Rotate the secret. Issues a new signing secret. The old one stops verifying at once.
- [POST /webhooks/test](https://www.1001sms.com/api-docs#webhooks-test): Send a ping. Sends a `ping` event to the URL now and returns the delivery outcome.
- [GET /webhooks/deliveries](https://www.1001sms.com/api-docs#webhooks-deliveries): Recent deliveries. The last deliveries to this key, newest first, each with the payload it carried. Kept for 30 days.
- [POST /webhooks/deliveries/{id}/retry](https://www.1001sms.com/api-docs#webhooks-retry): Re-send a delivery. Sends one delivery again now, whatever state it is in.

## Account

Balance, profile, transactions and usage statistics. https://www.1001sms.com/api-docs#account

- [GET /informative/balance](https://www.1001sms.com/api-docs#balance): Balance. Quick balance check.
- [GET /account/profile](https://www.1001sms.com/api-docs#profile): Profile. Main account fields.
- [GET /account/transactions](https://www.1001sms.com/api-docs#transactions): Transactions. Paginated ledger with optional type and status filters.
- [GET /account/transactions/{id}](https://www.1001sms.com/api-docs#transaction-by-id): One transaction. One transaction by id.
- [GET /account/stats](https://www.1001sms.com/api-docs#stats): Usage statistics. Aggregated usage across orders and transactions.

## Webhook events

- `sms.received` (SMS): An SMS arrived on an activation number or a virtual number. Fired the moment the provider tells us, and also when a poll finds a new message.
- `number.activated` (Virtual numbers): A virtual number was rented (by the API or on the website).
- `number.renewed` (Virtual numbers): A virtual number was renewed by you, the API or auto-renew.
- `number.renewal_failed` (Virtual numbers): Auto-renew ran and the balance was short.
- `number.expiring` (Virtual numbers): A number expires within a day (sent once per term).
- `number.expired` (Virtual numbers): A number's term ended.
- `number.cancelled` (Virtual numbers): An unlimited number was cancelled within its window and refunded.
- `esim.allocated` (eSIMs): An order received its activation code and QR.
- `esim.updated` (eSIMs): A profile's status or data usage changed (provider event or a refresh).
- `esim.failed` (eSIMs): The provider rejected the order after the balance was taken; the balance was refunded. There is no order id yet, so the request is echoed.
- `esim.refunded` (eSIMs): Support refunded the order.
- `ping` (Test): Sent by the test button and POST /webhooks/test. Always delivered, whatever the subscriptions.

Signature and payload details: https://www.1001sms.com/api-docs#webhook-signing

## Optional

- [OpenAPI 3.0 JSON](https://www.1001sms.com/api/v1/docs): machine-readable spec of every endpoint.
- [Full reference](https://www.1001sms.com/api-docs/llms-full.txt): every endpoint with parameters, examples and responses.
- [MCP server](https://www.1001sms.com/mcp-server): the same API as tools for AI agents.