Developers
Sim7 SMS API: orders, idempotency and secure webhooks
Begin with catalog and account reads: all available Sim7 client keys are production keys. Persist an Idempotency-Key before purchasing, receive signed notifications and reconcile order state. Repeating a request or event must not create another purchase or duplicate a customer-facing action.

Photo: Luca Bravo / Unsplash
In this guide
- Start with a dedicated key and non-purchase requests
- Read the catalog and price before user confirmation
- One purchase should correspond to one persisted operation
- Retry safely when the original response is lost
- Order states, multiple messages and completion
- Configure notifications before creating working orders
- Verify signatures against the original request bytes
- A repeated notification must not repeat a business action
- Handle limits and monitor without exposing SMS contents
- A production launch checklist
Start with a dedicated key and non-purchase requests
The client API base URL is https://sim7.org/api/v1. Create a dedicated integration key in the dashboard and grant only the required scopes: catalog:read for catalog data, account:read for account information, orders:read for reading orders, orders:write for purchases and actions, and webhooks:write for notification settings. Where appropriate, restrict allowed IP addresses or CIDR ranges.
The complete key is shown when created, so save it in server-side secret storage. Keep it out of browser JavaScript, mobile packages, public examples, request URLs and error logs. Send it as a Bearer token in the Authorization header. If a key is exposed publicly, revoke it and issue a replacement.
Start with GET /account, /balance, /services and /countries. These requests establish permissions, availability and limits without creating a number. All available client keys are production keys: POST /numbers makes a real purchase against a real account balance, not a free simulation.
Read current limits from /account. Additional keys do not multiply throughput because limits also apply at account level. Respect the currency field in responses; API amounts are USD regardless of the dashboard's ruble display.
curl -sS "https://sim7.org/api/v1/account" \
-H "Authorization: Bearer $SIM7_API_KEY"Read the catalog and price before user confirmation
Obtain a service ID from GET /services and a country ID from GET /countries rather than submitting a translated display name. Use GET /prices?service=... with an optional country parameter for current routes. The response contains the final price, availability and success information where known.
Prices already include the applicable Sim7 markup. Do not add it again when your intent is simply to display this API's price. If your product charges a separate fee, communicate it clearly and account for it separately from your purchase cost.
Price and availability can change between a catalog read and a purchase. Refresh the quote before confirmation and submit max_price as the maximum accepted final price in USD. This is a spending guard, not a promise that a number exists at that price.
Avoid selecting solely by the lowest value without checking conditions. Zero available stock and unknown success statistics are different situations. A success figure describes observed delivery outcomes; it does not guarantee the next activation.
One purchase should correspond to one persisted operation
Create a number with POST /numbers. The JSON body requires service and country. You may supply an exact operator or leave automatic selection. Passing max_price is recommended so a concurrent price change does not surprise your user.
Before the network request, persist a local operation record containing its internal ID, immutable parameters and a random Idempotency-Key. If your process restarts after sending, that record allows the original request to be recovered. Generating a fresh key for every network retry defeats duplicate protection.
A successful response provides an opaque order_id. Save it with your own order, the charged price and selected service. Use that ID for Sim7 reads and lifecycle actions, not the phone number. A telephone number is not a stable identifier for a business operation.
The example below illustrates the request shape rather than inviting a purchase with those exact values. Replace the route with current catalog results and the price ceiling explicitly accepted by your user.
POST /api/v1/numbers
Authorization: Bearer <server-side key>
Content-Type: application/json
Idempotency-Key: <persisted operation UUID>
{"service":"nvidia","country":"sweden","operator":"any","max_price":0.50}Retry safely when the original response is lost
Every public API mutation requires Idempotency-Key. An exact repeat returns the stored result when the operation has completed. Reusing the key for another path, method or body produces idempotency_conflict. Do not fix that conflict by blindly replacing the key; first establish which operation owns it.
A connection timeout does not prove that a number was never purchased. idempotency_in_progress means the original operation is running or its outcome needs reconciliation. Preserve the key and parameters instead of creating an unverified replacement. Support needs your operation reference, time and error code, not your Bearer secret.
Documented pre-allocation failures such as insufficient_funds, no_numbers_available and price_changed differ from an uncertain outcome. After resolving their cause, you can repeat the same request with the same key. If you change the price ceiling or other parameters, it is a different request: first establish that the earlier operation definitively did not create a number.
Completed idempotency responses are retained for seven days. Do not treat an old key as permanent protection or replay a long-completed purchase after that window. Your own operation journal should preserve the result for as long as your business workflow requires.
Order states, multiple messages and completion
GET /orders/{order_id} returns the current state and messages. waiting represents an order awaiting a message, code_received records an SMS, and completed means completion. cancelled, banned and expired are their respective terminal states. Do not infer the lifecycle solely from a phone number or a nonempty code field.
Use the messages array to display history because an active number may receive additional SMS. The first message should not automatically trigger POST /orders/{order_id}/finish when the user expects another verification. Completion is a separate, deliberate action.
Cancel and ban apply to waiting orders subject to action availability, while finish follows a received code. These POST requests need their own Idempotency-Key too. Do not manually credit a wallet merely because a cancellation was attempted: the financial outcome depends on the authoritative order state.
Use expires_at for a countdown rather than assigning twenty minutes to every order. Saved history does not receive future messages after closure. Cursor-paginated /orders reads can reconcile history; they are not a reason to recreate records automatically when local data appears incomplete.
Configure notifications before creating working orders
Register your public HTTPS receiver on the standard HTTPS port using PUT /webhook and select event names. Supported events include order.created, order.code_received, order.completed, order.cancelled, order.banned and order.expired. This address belongs to your integration; it is not an incoming route hosted on Sim7.
The signing secret is returned when created or rotated. Save it immediately with its version. An idempotent replay is not a vault for retrieving the original secret. GET /webhook lets you inspect configuration without revealing the secret again.
Sim7 expects a 2xx response within five seconds. Notifications can repeat: delivery has an initial attempt and four retries. Verify the signature, persist the event reliably and acknowledge only after successful storage. Perform slow business processing separately.
Disabling an endpoint cancels its queued attempts. Events before endpoint creation or during disabled periods are not automatically backfilled on enablement. Notifications should therefore complement periodic reconciliation of important order states rather than replace it completely.
Verify signatures against the original request bytes
X-Sim7-Signature contains v1= followed by a lowercase hexadecimal HMAC-SHA256 value. The signed input is the exact X-Sim7-Timestamp string, a dot and the raw JSON bytes. Parsing and reserializing JSON first may change spacing or field order and invalidate an otherwise correct signature.
The following example checks the signature, header formats, body size and a five-minute timestamp tolerance. That tolerance is a receiver policy in this example, not a change to the Sim7 protocol. Synchronize server clocks and select an acceptance window appropriate to expected network delay.
During rotation, respect X-Sim7-Secret-Version. A previously queued delivery retains its original secret version, while a retry receives a fresh timestamp. Keep necessary prior secrets until the old queue is finished. Do not pick an arbitrary secret when the version is unknown.
This function checks authenticity only. HTTP-level size limits, safe JSON parsing, schema validation, deduplication and updates to your own order remain separate required steps.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifySim7(rawBody, headers, secretsByVersion, now = Date.now()) {
if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
const timestamp = headers.get("x-sim7-timestamp") ?? "";
const signature = headers.get("x-sim7-signature") ?? "";
const version = headers.get("x-sim7-secret-version") ?? "";
if (!/^\d{10}$/.test(timestamp) || !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
if (!/^[1-9]\d{0,5}$/.test(version)) return false;
if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
const secret = secretsByVersion.get(Number(version));
if (typeof secret !== "string" || !secret) return false;
const expected = createHmac("sha256", secret)
.update(timestamp).update(".").update(rawBody).digest();
const received = Buffer.from(signature.slice(3), "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
}A repeated notification must not repeat a business action
After verifying the signature, parse the JSON and compare its id with X-Sim7-Delivery. Store the delivery ID in a table with a unique constraint. Register the accepted event and the permitted local order change, or a durable queue entry, within one transaction.
If that ID was already processed, return success without repeating fulfillment, a purchase or a credit. If your database is unavailable, do not acknowledge before storage: otherwise the sender considers delivery complete while your application has lost the event.
Verify that data.order_id belongs to an expected order in your integration. Do not move a completed local operation back to waiting because of stale application state. Keep message history separate from the compact lifecycle status.
GET /webhook/deliveries provides attempt and delivery outcomes. When a notification has permanently failed, read the order and perform controlled reconciliation. Creating another number is not a remedy for a missed notification.
Handle limits and monitor without exposing SMS contents
Branch on error.code rather than matching text in the human-readable message. For 401, inspect the key; for 403, inspect permissions and the IP allowlist; for 429, reduce load. Transient 5xx responses permit cautious retries with backoff, but a purchase must retain its original key and uncertain-outcome handling.
Concurrent status reads do not necessarily trigger equally frequent upstream checks. Sim7 uses local snapshots and a provider-poll lease. Polling dozens of times per second adds load without guaranteeing a faster code. Prefer webhooks plus moderate fallback polling.
Useful metrics include purchases, errors by code, SMS waiting time, the age of unresolved operations and webhook failures. Keep SMS text, telephone numbers, API tokens and signing secrets out of public logs and third-party analytics.
Apply spending limits in your own product and alert on unresolved purchases. Monitoring should identify an operation requiring reconciliation before a customer starts pressing the purchase control repeatedly.
A production launch checklist
First test your receiver using local fixtures: a valid signature, a modified body, an old timestamp, an unknown secret version and repeated delivery of one ID. None of these tests requires purchasing a number. Next, verify read requests with a dedicated production key.
A controlled real purchase should be a separate intentional test with an agreed spending ceiling. Check order_id persistence, messages display, permitted actions, exact replay with the original idempotency key and recovery after restarting your own process.
Record the contract review date and the current documentation URL. When the API changes, update integration tests and interface copy together. Reliability depends on handling repeats and uncertain outcomes, not only on receiving a tidy response to the first successful request.
Assign an owner for these incidents with safe access to the operation journal and order reference, not exposed credentials. This makes investigation faster and helps explain the actual outcome to the user.
Sources & review
Reviewed: 2026-11-09 · Sim7 Editorial. Interfaces and service policies can change. Check the requirements in your own account before buying.




