Documentation

Sim7 API

One endpoint to buy, one for status, one for the incoming SMS. Every request goes to https://sim7.org/api/v1 and is authorized with a bearer token.

Base URL

base_url

https://sim7.org/api/v1

HTTPS only, request and response bodies are JSON in UTF-8.

Authorization header

Bearer

Authorization

Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx

The key is available under API keys in your dashboard. nx_test keys run in the sandbox with no charges.

Getting started

Base URL, response format, and your first request in five minutes.

All requests go to https://sim7.org/api/v1 over HTTPS. Request and response bodies are JSON, UTF-8 encoded; requests without TLS are rejected outright, with no redirect to a secure connection.

A successful response always contains a data object. An error returns an object with code and message fields: code is a stable machine identifier, message is human-readable text for logs and UI. Branch your code on code, not on the HTTP status.

Amounts are returned in US dollars as a floating-point number rounded to four decimal places. All timestamps are in UTC, ISO 8601 format.

Authentication

Bearer token in the header, test and live keys, IP allowlisting.

The key is sent in a header: Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx. Keys prefixed nx_live operate on your real balance; nx_test keys run in a sandbox where orders go through the full lifecycle but nothing is ever charged.

A key is issued right after signup and is visible under "API keys" in the dashboard. Rotating it revokes the old key immediately, so update it across every integration at the same time.

For a live key, we recommend enabling an IP allowlist: requests from other addresses get an ip_not_allowed error even with a valid key.

Catalog and pricing

Services, countries, and live pricing with number availability.

The catalog changes rarely, so you can cache the service and country lists on your end — a one-hour refresh interval is reasonable.

Prices and availability, on the other hand, live for minutes: they depend on the current state of the pools. Fetch them right before purchase so you don't show the user a stale figure.

GET/services

List services

Returns the service catalog with category and minimum number price.

Parameters

Parameter	Where	Type	Example:
categoryOptional	Query	string	Filter by catalog category.Example: `messengers`
searchOptional	Query	string	Case-insensitive search by service name.Example: `tele`

categoryQueryOptional
Filter by catalog category.
string · Example: messengers
searchQueryOptional
Case-insensitive search by service name.
string · Example: tele

curl

curl -s https://sim7.org/api/v1/services \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "telegram", "name": "Telegram", "category": "Messengers", "price_from": 0.12, "available": 48210 },
    { "id": "whatsapp", "name": "WhatsApp", "category": "Messengers", "price_from": 0.09, "available": 36540 }
  ],
  "total": 1240
}

GET/countries

List countries

Returns countries, dial code, and the number of available numbers.

Parameters

Parameter	Where	Type	Example:
regionOptional	Query	string	Filter by region: europe, asia, america, or africa.Example: `europe`

regionQueryOptional
Filter by region: europe, asia, america, or africa.
string · Example: europe

curl

curl -s "https://sim7.org/api/v1/countries?region=europe" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "germany", "name": "Germany", "iso": "DE", "dial": "+49", "available": 27600 },
    { "id": "france", "name": "France", "iso": "FR", "dial": "+33", "available": 21900 }
  ],
  "total": 195
}

GET/prices

Prices and availability

Live price and remaining numbers for a service + country pair. Data lives for about a minute — don't cache it for long.

Parameters

Parameter	Where	Type	Example:
serviceRequired	Query	string	Service identifier from the catalog.Example: `telegram`
countryOptional	Query	string	Country identifier. Omit it to get all countries for the service.Example: `russia`

serviceQueryRequired
Service identifier from the catalog.
string · Example: telegram
countryQueryOptional
Country identifier. Omit it to get all countries for the service.
string · Example: russia

curl

curl -s "https://sim7.org/api/v1/prices?service=telegram&country=russia" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "service": "telegram",
  "items": [
    {
      "country": "russia",
      "operator": "any",
      "price": 0.12,
      "available": 18240,
      "success_rate": 0.978
    }
  ]
}

Orders

Buying a number, receiving the code, canceling, and re-renting.

An order moves through waiting → completed or waiting → cancelled. While an order is waiting, the number is locked to you and receiving messages; the default waiting window is 1200 seconds.

If the code hasn't arrived by the end of the window, the order automatically moves to cancelled and the amount is refunded to your balance. No separate refund request is needed.

Don't poll the status more than once every five seconds — set up a webhook instead, and use polling only as a safety net for orders that are taking longer than usual.

POST/numbers

Buy a number

Reserves a number for the chosen service and creates an order in waiting status. The amount is charged immediately and refunded if no code arrives.

Parameters

Parameter	Where	Type	Example:
serviceRequired	Body	string	Identifier of the service you need a number for.Example: `telegram`
countryRequired	Body	string	Country identifier.Example: `russia`
operatorOptional	Body	string	Operator identifier. Defaults to any — picked automatically for deliverability.Example: `mts`
max_priceOptional	Body	number	Price protection: the order won't be created if the number costs more than this amount.Example: `0.2`
ttl_secondsOptional	Body	number	SMS waiting window in seconds, from 300 to 3600. Defaults to 1200.Example: `1200`

serviceBodyRequired
Identifier of the service you need a number for.
string · Example: telegram
countryBodyRequired
Country identifier.
string · Example: russia
operatorBodyOptional
Operator identifier. Defaults to any — picked automatically for deliverability.
string · Example: mts
max_priceBodyOptional
Price protection: the order won't be created if the number costs more than this amount.
number · Example: 0.2
ttl_secondsBodyOptional
SMS waiting window in seconds, from 300 to 3600. Defaults to 1200.
number · Example: 1200

curl

curl -s -X POST https://sim7.org/api/v1/numbers \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"russia","max_price":0.2}'

request.json

{
  "service": "telegram",
  "country": "russia",
  "operator": "any",
  "max_price": 0.2,
  "ttl_seconds": 1200
}

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "service": "telegram",
  "country": "russia",
  "operator": "mts",
  "price": 0.12,
  "status": "waiting",
  "expires_at": "2026-07-31T18:32:00Z"
}

GET/orders/{order_id}

Order status and code

Returns the current order status and every message received. The code field is null until a code arrives.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Order identifier returned when the number was purchased.Example: `a13f9c`

order_idPathRequired
Order identifier returned when the number was purchased.
string · Example: a13f9c

curl

curl -s https://sim7.org/api/v1/orders/a13f9c \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "status": "completed",
  "code": "482913",
  "price": 0.12,
  "messages": [
    {
      "sender": "Telegram",
      "text": "Your login code: 482913",
      "received_at": "2026-07-31T18:12:44Z"
    }
  ]
}

GET/orders

Order history

Paginated list of account orders, newest first.

Parameters

Parameter	Where	Type	Example:
statusOptional	Query	string	Filter by status: waiting, completed, or cancelled.Example: `completed`
limitOptional	Query	number	Page size, from 1 to 100. Defaults to 20.Example: `20`
cursorOptional	Query	string	Next-page cursor from the previous response's next_cursor field.Example: `b27e41`

statusQueryOptional
Filter by status: waiting, completed, or cancelled.
string · Example: completed
limitQueryOptional
Page size, from 1 to 100. Defaults to 20.
number · Example: 20
cursorQueryOptional
Next-page cursor from the previous response's next_cursor field.
string · Example: b27e41

curl

curl -s "https://sim7.org/api/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    {
      "order_id": "a13f9c",
      "service": "telegram",
      "country": "russia",
      "number": "+7 901 234 56 78",
      "code": "482913",
      "price": 0.12,
      "status": "completed",
      "created_at": "2026-07-29T14:12:00Z"
    }
  ],
  "next_cursor": "b27e41"
}

POST/orders/{order_id}/cancel

Cancel an order

Releases the number early. If the code hasn't arrived yet, the amount is refunded to your balance in full.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Identifier of an order in waiting status.Example: `c88a02`

order_idPathRequired
Identifier of an order in waiting status.
string · Example: c88a02

curl

curl -s -X POST https://sim7.org/api/v1/orders/c88a02/cancel \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "c88a02",
  "status": "cancelled",
  "refunded": 0.05,
  "balance": 24.85
}

POST/orders/{order_id}/reuse

Re-rent a number

Creates a new order for the same number if it's still free. Cheaper than buying a new number.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Identifier of a completed order.Example: `a13f9c`
serviceOptional	Body	string	A different service for the same number. Defaults to the original order's service.Example: `whatsapp`

order_idPathRequired
Identifier of a completed order.
string · Example: a13f9c
serviceBodyOptional
A different service for the same number. Defaults to the original order's service.
string · Example: whatsapp

curl

curl -s -X POST https://sim7.org/api/v1/orders/a13f9c/reuse \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp"}'

request.json

{
  "service": "whatsapp"
}

response.json

{
  "order_id": "f0271d",
  "number": "+7 901 234 56 78",
  "service": "whatsapp",
  "price": 0.07,
  "status": "waiting",
  "expires_at": "2026-07-31T19:04:00Z"
}

Account

Balance, limits, and account statistics.

Check your balance before a batch of purchases: if funds are insufficient, a number request returns an insufficient_funds error and no order is created.

The response also includes your current account limits — the number of concurrent active orders and remaining request-rate headroom. That's more reliable than reverse-engineering the limits from 429 errors.

GET/balance

Balance and limits

Current account balance, active plan, and remaining limits.

curl

curl -s https://sim7.org/api/v1/balance \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "balance": 24.8,
  "currency": "USD",
  "plan": "api",
  "limits": {
    "concurrent_orders": 250,
    "active_orders": 3,
    "requests_per_minute": 600
  }
}

Webhooks

Instant notification when a code arrives, plus signature verification.

We send a POST request to your address the moment a message is parsed. Every request is signed with the X-Sim7-Signature header: the signature is HMAC-SHA256 over the raw request body, keyed with your webhook secret.

Verify the signature before parsing the body, and compare it using a constant-time function. Your handler must respond with status 200 within five seconds.

Delivery is guaranteed at least once, so your handler must be idempotent on order_id. On failure, we retry five times with a growing interval from 10 seconds up to 5 minutes.

PUT/webhook

Configure a webhook

Sets the handler URL and the list of events. The signing secret is returned once, at creation time.

Parameters

Parameter	Where	Type	Example:
urlRequired	Body	string	HTTPS handler URL.Example: `https://sim7.org/webhooks/sim7`
eventsRequired	Body	string	Events: order.code_received, order.cancelled, balance.low.Example: `order.code_received`
is_enabledOptional	Body	boolean	Lets you temporarily disable delivery without deleting the setting.Example: `true`

urlBodyRequired
HTTPS handler URL.
string · Example: https://sim7.org/webhooks/sim7
eventsBodyRequired
Events: order.code_received, order.cancelled, balance.low.
string · Example: order.code_received
is_enabledBodyOptional
Lets you temporarily disable delivery without deleting the setting.
boolean · Example: true

curl

curl -s -X PUT https://sim7.org/api/v1/webhook \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://sim7.org/webhooks/sim7","events":["order.code_received"]}'

request.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true
}

response.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true,
  "secret": "whsec_9f31c0a7d84b2e65",
  "updated_at": "2026-07-31T18:40:12Z"
}

POSThttps://sim7.org/webhooks/sim7

order.code_received event

The request we send to your address once a message is parsed. Respond with status 200 within five seconds.

Parameters

Parameter	Where	Type	Example:
eventRequired	Body	string	Event type.Example: `order.code_received`
order_idRequired	Body	string	Order identifier — use it as your idempotency key.Example: `a13f9c`
codeRequired	Body	string	The code extracted from the message text.Example: `482913`

eventBodyRequired
Event type.
string · Example: order.code_received
order_idBodyRequired
Order identifier — use it as your idempotency key.
string · Example: a13f9c
codeBodyRequired
The code extracted from the message text.
string · Example: 482913

curl

# we send this request; here's how to replay it locally:
curl -s -X POST https://sim7.org/webhooks/sim7 \
  -H "Content-Type: application/json" \
  -H "X-Sim7-Signature: sha256=1f8c…" \
  -d '{"event":"order.code_received","order_id":"a13f9c","code":"482913"}'

request.json

{
  "event": "order.code_received",
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "code": "482913",
  "text": "Your login code: 482913",
  "received_at": "2026-07-31T18:12:44Z"
}

response.json

{
  "received": true
}

Errors and limits

Stable error codes and per-plan request rates.

Client errors (4xx) mean the request itself needs fixing — retrying it unchanged won't help. 5xx and 429 errors can be retried with exponential backoff.

When the request rate is exceeded, the response includes a Retry-After header with the number of seconds until the next allowed attempt.

Error codes

Sim7 API error codes
Code	HTTP	What happened
`invalid_request`	400	Invalid requestThe body or parameters fail validation: a required field is missing or the wrong type.
`unauthorized`	401	Key not acceptedThe Authorization header is missing, the key was revoked, or it was copied incompletely.
`ip_not_allowed`	403	IP not allowlistedThe key is valid, but the request came from an address that isn't on the account's allowlist.
`order_not_found`	404	Order not foundNo order exists with that identifier, or it belongs to another account.
`order_not_cancellable`	409	Order already closedCancellation only works for orders in waiting status: the code already arrived, or the window expired.
`insufficient_funds`	402	Insufficient fundsThe balance doesn't cover the chosen number. No order was created, nothing was charged.
`no_numbers_available`	409	No numbers availableThe pool for that service + country pair is temporarily empty. Retry later or switch countries.
`price_changed`	409	Price above limitThe current price exceeded the request's max_price. Refresh the price and retry the purchase.
`rate_limited`	429	Too many requestsThe request rate was exceeded. Wait for the number of seconds in the Retry-After header.
`concurrency_limit`	429	Active-order limitThe plan's concurrent-order limit was reached. Wait for current orders to finish.
`internal_error`	500	Internal errorA failure on our side. The request can be retried with exponential backoff.
`service_unavailable`	503	Service unavailableScheduled maintenance or degradation. We publish the current state on the status page.

invalid_request400
Invalid request
The body or parameters fail validation: a required field is missing or the wrong type.
unauthorized401
Key not accepted
The Authorization header is missing, the key was revoked, or it was copied incompletely.
ip_not_allowed403
IP not allowlisted
The key is valid, but the request came from an address that isn't on the account's allowlist.
order_not_found404
Order not found
No order exists with that identifier, or it belongs to another account.
order_not_cancellable409
Order already closed
Cancellation only works for orders in waiting status: the code already arrived, or the window expired.
insufficient_funds402
Insufficient funds
The balance doesn't cover the chosen number. No order was created, nothing was charged.
no_numbers_available409
No numbers available
The pool for that service + country pair is temporarily empty. Retry later or switch countries.
price_changed409
Price above limit
The current price exceeded the request's max_price. Refresh the price and retry the purchase.
rate_limited429
Too many requests
The request rate was exceeded. Wait for the number of seconds in the Retry-After header.
concurrency_limit429
Active-order limit
The plan's concurrent-order limit was reached. Wait for current orders to finish.
internal_error500
Internal error
A failure on our side. The request can be retried with exponential backoff.
service_unavailable503
Service unavailable
Scheduled maintenance or degradation. We publish the current state on the status page.

Request rate

Per-plan request rate limits
Plan	Requests / min	Notes
One-off purchase	60	Up to 10 concurrent active orders.
Developer API	600	Up to 250 concurrent active orders.
Business	On request	Limits are negotiated for your load, with no concurrent-order cap.
Test key nx_test	120	A sandbox with no charges; the code arrives in 3–5 seconds.

One-off purchase60
Up to 10 concurrent active orders.
Developer API600
Up to 250 concurrent active orders.
BusinessOn request
Limits are negotiated for your load, with no concurrent-order cap.
Test key nx_test120
A sandbox with no charges; the code arrives in 3–5 seconds.

We publish the current state of every component and the incident history on the status page.

Ready to try it?

A key is issued right after signup, the sandbox doesn't touch your balance, and webhook signatures are verified against the X-Sim7-Signature header.

Get an access key My API keys

Documentation

Sim7 API

One endpoint to buy, one for status, one for the incoming SMS. Every request goes to https://sim7.org/api/v1 and is authorized with a bearer token.

Base URL

base_url

https://sim7.org/api/v1

HTTPS only, request and response bodies are JSON in UTF-8.

Authorization header

Bearer

Authorization

Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx

The key is available under API keys in your dashboard. nx_test keys run in the sandbox with no charges.

Getting started

Base URL, response format, and your first request in five minutes.

All requests go to https://sim7.org/api/v1 over HTTPS. Request and response bodies are JSON, UTF-8 encoded; requests without TLS are rejected outright, with no redirect to a secure connection.

Amounts are returned in US dollars as a floating-point number rounded to four decimal places. All timestamps are in UTC, ISO 8601 format.

Authentication

Bearer token in the header, test and live keys, IP allowlisting.

A key is issued right after signup and is visible under "API keys" in the dashboard. Rotating it revokes the old key immediately, so update it across every integration at the same time.

For a live key, we recommend enabling an IP allowlist: requests from other addresses get an ip_not_allowed error even with a valid key.

Catalog and pricing

Services, countries, and live pricing with number availability.

The catalog changes rarely, so you can cache the service and country lists on your end — a one-hour refresh interval is reasonable.

Prices and availability, on the other hand, live for minutes: they depend on the current state of the pools. Fetch them right before purchase so you don't show the user a stale figure.

GET/services

List services

Returns the service catalog with category and minimum number price.

Parameters

Parameter	Where	Type	Example:
categoryOptional	Query	string	Filter by catalog category.Example: `messengers`
searchOptional	Query	string	Case-insensitive search by service name.Example: `tele`

categoryQueryOptional
Filter by catalog category.
string · Example: messengers
searchQueryOptional
Case-insensitive search by service name.
string · Example: tele

curl

curl -s https://sim7.org/api/v1/services \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "telegram", "name": "Telegram", "category": "Messengers", "price_from": 0.12, "available": 48210 },
    { "id": "whatsapp", "name": "WhatsApp", "category": "Messengers", "price_from": 0.09, "available": 36540 }
  ],
  "total": 1240
}

GET/countries

List countries

Returns countries, dial code, and the number of available numbers.

Parameters

Parameter	Where	Type	Example:
regionOptional	Query	string	Filter by region: europe, asia, america, or africa.Example: `europe`

regionQueryOptional
Filter by region: europe, asia, america, or africa.
string · Example: europe

curl

curl -s "https://sim7.org/api/v1/countries?region=europe" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "germany", "name": "Germany", "iso": "DE", "dial": "+49", "available": 27600 },
    { "id": "france", "name": "France", "iso": "FR", "dial": "+33", "available": 21900 }
  ],
  "total": 195
}

GET/prices

Prices and availability

Live price and remaining numbers for a service + country pair. Data lives for about a minute — don't cache it for long.

Parameters

Parameter	Where	Type	Example:
serviceRequired	Query	string	Service identifier from the catalog.Example: `telegram`
countryOptional	Query	string	Country identifier. Omit it to get all countries for the service.Example: `russia`

serviceQueryRequired
Service identifier from the catalog.
string · Example: telegram
countryQueryOptional
Country identifier. Omit it to get all countries for the service.
string · Example: russia

curl

curl -s "https://sim7.org/api/v1/prices?service=telegram&country=russia" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "service": "telegram",
  "items": [
    {
      "country": "russia",
      "operator": "any",
      "price": 0.12,
      "available": 18240,
      "success_rate": 0.978
    }
  ]
}

Orders

Buying a number, receiving the code, canceling, and re-renting.

An order moves through waiting → completed or waiting → cancelled. While an order is waiting, the number is locked to you and receiving messages; the default waiting window is 1200 seconds.

If the code hasn't arrived by the end of the window, the order automatically moves to cancelled and the amount is refunded to your balance. No separate refund request is needed.

Don't poll the status more than once every five seconds — set up a webhook instead, and use polling only as a safety net for orders that are taking longer than usual.

POST/numbers

Buy a number

Reserves a number for the chosen service and creates an order in waiting status. The amount is charged immediately and refunded if no code arrives.

Parameters

Parameter	Where	Type	Example:
serviceRequired	Body	string	Identifier of the service you need a number for.Example: `telegram`
countryRequired	Body	string	Country identifier.Example: `russia`
operatorOptional	Body	string	Operator identifier. Defaults to any — picked automatically for deliverability.Example: `mts`
max_priceOptional	Body	number	Price protection: the order won't be created if the number costs more than this amount.Example: `0.2`
ttl_secondsOptional	Body	number	SMS waiting window in seconds, from 300 to 3600. Defaults to 1200.Example: `1200`

serviceBodyRequired
Identifier of the service you need a number for.
string · Example: telegram
countryBodyRequired
Country identifier.
string · Example: russia
operatorBodyOptional
Operator identifier. Defaults to any — picked automatically for deliverability.
string · Example: mts
max_priceBodyOptional
Price protection: the order won't be created if the number costs more than this amount.
number · Example: 0.2
ttl_secondsBodyOptional
SMS waiting window in seconds, from 300 to 3600. Defaults to 1200.
number · Example: 1200

curl

curl -s -X POST https://sim7.org/api/v1/numbers \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"russia","max_price":0.2}'

request.json

{
  "service": "telegram",
  "country": "russia",
  "operator": "any",
  "max_price": 0.2,
  "ttl_seconds": 1200
}

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "service": "telegram",
  "country": "russia",
  "operator": "mts",
  "price": 0.12,
  "status": "waiting",
  "expires_at": "2026-07-31T18:32:00Z"
}

GET/orders/{order_id}

Order status and code

Returns the current order status and every message received. The code field is null until a code arrives.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Order identifier returned when the number was purchased.Example: `a13f9c`

order_idPathRequired
Order identifier returned when the number was purchased.
string · Example: a13f9c

curl

curl -s https://sim7.org/api/v1/orders/a13f9c \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "status": "completed",
  "code": "482913",
  "price": 0.12,
  "messages": [
    {
      "sender": "Telegram",
      "text": "Your login code: 482913",
      "received_at": "2026-07-31T18:12:44Z"
    }
  ]
}

GET/orders

Order history

Paginated list of account orders, newest first.

Parameters

Parameter	Where	Type	Example:
statusOptional	Query	string	Filter by status: waiting, completed, or cancelled.Example: `completed`
limitOptional	Query	number	Page size, from 1 to 100. Defaults to 20.Example: `20`
cursorOptional	Query	string	Next-page cursor from the previous response's next_cursor field.Example: `b27e41`

statusQueryOptional
Filter by status: waiting, completed, or cancelled.
string · Example: completed
limitQueryOptional
Page size, from 1 to 100. Defaults to 20.
number · Example: 20
cursorQueryOptional
Next-page cursor from the previous response's next_cursor field.
string · Example: b27e41

curl

curl -s "https://sim7.org/api/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    {
      "order_id": "a13f9c",
      "service": "telegram",
      "country": "russia",
      "number": "+7 901 234 56 78",
      "code": "482913",
      "price": 0.12,
      "status": "completed",
      "created_at": "2026-07-29T14:12:00Z"
    }
  ],
  "next_cursor": "b27e41"
}

POST/orders/{order_id}/cancel

Cancel an order

Releases the number early. If the code hasn't arrived yet, the amount is refunded to your balance in full.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Identifier of an order in waiting status.Example: `c88a02`

order_idPathRequired
Identifier of an order in waiting status.
string · Example: c88a02

curl

curl -s -X POST https://sim7.org/api/v1/orders/c88a02/cancel \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "c88a02",
  "status": "cancelled",
  "refunded": 0.05,
  "balance": 24.85
}

POST/orders/{order_id}/reuse

Re-rent a number

Creates a new order for the same number if it's still free. Cheaper than buying a new number.

Parameters

Parameter	Where	Type	Example:
order_idRequired	Path	string	Identifier of a completed order.Example: `a13f9c`
serviceOptional	Body	string	A different service for the same number. Defaults to the original order's service.Example: `whatsapp`

order_idPathRequired
Identifier of a completed order.
string · Example: a13f9c
serviceBodyOptional
A different service for the same number. Defaults to the original order's service.
string · Example: whatsapp

curl

curl -s -X POST https://sim7.org/api/v1/orders/a13f9c/reuse \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp"}'

request.json

{
  "service": "whatsapp"
}

response.json

{
  "order_id": "f0271d",
  "number": "+7 901 234 56 78",
  "service": "whatsapp",
  "price": 0.07,
  "status": "waiting",
  "expires_at": "2026-07-31T19:04:00Z"
}

Account

Balance, limits, and account statistics.

Check your balance before a batch of purchases: if funds are insufficient, a number request returns an insufficient_funds error and no order is created.

GET/balance

Balance and limits

Current account balance, active plan, and remaining limits.

curl

curl -s https://sim7.org/api/v1/balance \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "balance": 24.8,
  "currency": "USD",
  "plan": "api",
  "limits": {
    "concurrent_orders": 250,
    "active_orders": 3,
    "requests_per_minute": 600
  }
}

Webhooks

Instant notification when a code arrives, plus signature verification.

Verify the signature before parsing the body, and compare it using a constant-time function. Your handler must respond with status 200 within five seconds.

Delivery is guaranteed at least once, so your handler must be idempotent on order_id. On failure, we retry five times with a growing interval from 10 seconds up to 5 minutes.

PUT/webhook

Configure a webhook

Sets the handler URL and the list of events. The signing secret is returned once, at creation time.

Parameters

Parameter	Where	Type	Example:
urlRequired	Body	string	HTTPS handler URL.Example: `https://sim7.org/webhooks/sim7`
eventsRequired	Body	string	Events: order.code_received, order.cancelled, balance.low.Example: `order.code_received`
is_enabledOptional	Body	boolean	Lets you temporarily disable delivery without deleting the setting.Example: `true`

urlBodyRequired
HTTPS handler URL.
string · Example: https://sim7.org/webhooks/sim7
eventsBodyRequired
Events: order.code_received, order.cancelled, balance.low.
string · Example: order.code_received
is_enabledBodyOptional
Lets you temporarily disable delivery without deleting the setting.
boolean · Example: true

curl

curl -s -X PUT https://sim7.org/api/v1/webhook \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://sim7.org/webhooks/sim7","events":["order.code_received"]}'

request.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true
}

response.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true,
  "secret": "whsec_9f31c0a7d84b2e65",
  "updated_at": "2026-07-31T18:40:12Z"
}

POSThttps://sim7.org/webhooks/sim7

order.code_received event

The request we send to your address once a message is parsed. Respond with status 200 within five seconds.

Parameters

Parameter	Where	Type	Example:
eventRequired	Body	string	Event type.Example: `order.code_received`
order_idRequired	Body	string	Order identifier — use it as your idempotency key.Example: `a13f9c`
codeRequired	Body	string	The code extracted from the message text.Example: `482913`

eventBodyRequired
Event type.
string · Example: order.code_received
order_idBodyRequired
Order identifier — use it as your idempotency key.
string · Example: a13f9c
codeBodyRequired
The code extracted from the message text.
string · Example: 482913

curl

# we send this request; here's how to replay it locally:
curl -s -X POST https://sim7.org/webhooks/sim7 \
  -H "Content-Type: application/json" \
  -H "X-Sim7-Signature: sha256=1f8c…" \
  -d '{"event":"order.code_received","order_id":"a13f9c","code":"482913"}'

request.json

{
  "event": "order.code_received",
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "code": "482913",
  "text": "Your login code: 482913",
  "received_at": "2026-07-31T18:12:44Z"
}

response.json

{
  "received": true
}

Errors and limits

Stable error codes and per-plan request rates.

Client errors (4xx) mean the request itself needs fixing — retrying it unchanged won't help. 5xx and 429 errors can be retried with exponential backoff.

When the request rate is exceeded, the response includes a Retry-After header with the number of seconds until the next allowed attempt.

Error codes

Sim7 API error codes
Code	HTTP	What happened
`invalid_request`	400	Invalid requestThe body or parameters fail validation: a required field is missing or the wrong type.
`unauthorized`	401	Key not acceptedThe Authorization header is missing, the key was revoked, or it was copied incompletely.
`ip_not_allowed`	403	IP not allowlistedThe key is valid, but the request came from an address that isn't on the account's allowlist.
`order_not_found`	404	Order not foundNo order exists with that identifier, or it belongs to another account.
`order_not_cancellable`	409	Order already closedCancellation only works for orders in waiting status: the code already arrived, or the window expired.
`insufficient_funds`	402	Insufficient fundsThe balance doesn't cover the chosen number. No order was created, nothing was charged.
`no_numbers_available`	409	No numbers availableThe pool for that service + country pair is temporarily empty. Retry later or switch countries.
`price_changed`	409	Price above limitThe current price exceeded the request's max_price. Refresh the price and retry the purchase.
`rate_limited`	429	Too many requestsThe request rate was exceeded. Wait for the number of seconds in the Retry-After header.
`concurrency_limit`	429	Active-order limitThe plan's concurrent-order limit was reached. Wait for current orders to finish.
`internal_error`	500	Internal errorA failure on our side. The request can be retried with exponential backoff.
`service_unavailable`	503	Service unavailableScheduled maintenance or degradation. We publish the current state on the status page.

invalid_request400
Invalid request
The body or parameters fail validation: a required field is missing or the wrong type.
unauthorized401
Key not accepted
The Authorization header is missing, the key was revoked, or it was copied incompletely.
ip_not_allowed403
IP not allowlisted
The key is valid, but the request came from an address that isn't on the account's allowlist.
order_not_found404
Order not found
No order exists with that identifier, or it belongs to another account.
order_not_cancellable409
Order already closed
Cancellation only works for orders in waiting status: the code already arrived, or the window expired.
insufficient_funds402
Insufficient funds
The balance doesn't cover the chosen number. No order was created, nothing was charged.
no_numbers_available409
No numbers available
The pool for that service + country pair is temporarily empty. Retry later or switch countries.
price_changed409
Price above limit
The current price exceeded the request's max_price. Refresh the price and retry the purchase.
rate_limited429
Too many requests
The request rate was exceeded. Wait for the number of seconds in the Retry-After header.
concurrency_limit429
Active-order limit
The plan's concurrent-order limit was reached. Wait for current orders to finish.
internal_error500
Internal error
A failure on our side. The request can be retried with exponential backoff.
service_unavailable503
Service unavailable
Scheduled maintenance or degradation. We publish the current state on the status page.

Request rate

Per-plan request rate limits
Plan	Requests / min	Notes
One-off purchase	60	Up to 10 concurrent active orders.
Developer API	600	Up to 250 concurrent active orders.
Business	On request	Limits are negotiated for your load, with no concurrent-order cap.
Test key nx_test	120	A sandbox with no charges; the code arrives in 3–5 seconds.

One-off purchase60
Up to 10 concurrent active orders.
Developer API600
Up to 250 concurrent active orders.
BusinessOn request
Limits are negotiated for your load, with no concurrent-order cap.
Test key nx_test120
A sandbox with no charges; the code arrives in 3–5 seconds.

We publish the current state of every component and the incident history on the status page.

Ready to try it?

A key is issued right after signup, the sandbox doesn't touch your balance, and webhook signatures are verified against the X-Sim7-Signature header.

Get an access key My API keys

Base URL

Authorization header

Getting started

Authentication

Catalog and pricing

List services

Parameters

List countries

Parameters

Prices and availability

Parameters

Orders

Buy a number

Parameters

Order status and code

Parameters

Order history

Parameters

Cancel an order

Parameters

Re-rent a number

Parameters

Account

Balance and limits

Webhooks

Configure a webhook

Parameters

order.code_received event

Parameters

Errors and limits

Error codes

Request rate

Ready to try it?

Собираем страницу

Base URL

Authorization header

Getting started

Authentication

Catalog and pricing

List services

Parameters

List countries

Parameters

Prices and availability

Parameters

Orders

Buy a number

Parameters

Order status and code

Parameters

Order history

Parameters

Cancel an order

Parameters

Re-rent a number

Parameters

Account

Balance and limits

Webhooks

Configure a webhook

Parameters

order.code_received event

Parameters

Errors and limits

Error codes

Request rate

Ready to try it?