HidSimAPI
OpenAPI JSONAPI reference

Order a number.Poll the operation.Read the code.

A small, stable partner API: sign in once, buy a number, then poll its operation until the code arrives.

API referenceOpenAPI JSON
https://a.hidsim.com
GET/operations/67af812efe2a49d3f54e3eebpoll 3
Authorization: Bearer $TOKEN
Response200completed
{  "_id": "67af812efe2a49d3f54e3eeb",  "id": "ifjuxhdz",  "status": "completed",  "number": 905396855192,  "code": "766892",  "message": "[Apple] Apple 766892",  "messages": [{ "text": "[Apple] Apple 766892", "code": "766892" }]}

Read code, not message.

Final status reached. Polling stops here.
18

Endpoints, documented in OpenAPI 3. Anything else is internal.

JWT

Bearer token. Sign in once, reuse it while its session lives.

async

Every purchase returns an operation you poll to a final status.

same price

One number at the website's price, from the same coin balance.

From sign-in to SMS code

Four steps cover the whole integration. The order answers at once with an operation, and the code arrives later on the operation you poll.

Sign in

Send your HidSim email and password once. The token comes back with your user and balance; reuse it on every protected call.

  • POST/auth/login
Request
curl -X POST https://a.hidsim.com/auth/login \  -H "Content-Type: application/json" \  -d '{"identifier":"[email protected]","password":"secret-password"}'
Response200
{  "token": "<jwt>",  "user": {    "_id": "67af6495fe2a49d3f54db241",    "id": "u7f92kq1",    "balance": 24.85,    "role": "user"  }}

Send it as Authorization: Bearer on every protected call.

Find inventory

List countries, search a service, then read the products you can buy for that pair.

  • GET/countries
  • GET/services/search
  • GET/products
Requests
# countriescurl "https://a.hidsim.com/countries?status=available&limit=100" \  -H "preferred-lng: en"# search a servicecurl "https://a.hidsim.com/services/search?text=whatsapp&status=available&limit=20" \  -H "preferred-lng: en"# products for that paircurl "https://a.hidsim.com/products?_service=666cbd28148aad58051c0669&_country=666d878021d0c45a725fa496&status=available"

Skip a product while its cooldown.until is in the future: it is out of stock until then.

Place the order

Buy one exact product, or buy by service and let HidSim pick within your price window, across one or more countries.

  • POST/products/{productId}/purchase
  • POST/services/{serviceId}/purchase
Request
curl -X POST https://a.hidsim.com/services/666cbd28148aad58051c0669/purchase \  -H "Authorization: Bearer $TOKEN" \  -H "Content-Type: application/json" \  -d '{"minPrice":0,"maxPrice":2.5,"_countryIds":["666d878021d0c45a725fa496"]}'
Responsecreating
{  "_id": "67af812efe2a49d3f54e3eeb",  "id": "ifjuxhdz",  "status": "creating"}

An operation, at once, still creating or pending.

Poll for the code

Poll while the status is creating or pending, and stop at a final status. Refunds are normal outcomes, not transport errors.

  • GET/operations/{operationId}
Request
curl https://a.hidsim.com/operations/67af812efe2a49d3f54e3eeb \  -H "Authorization: Bearer $TOKEN"
Response200completed
{  "_id": "67af812efe2a49d3f54e3eeb",  "id": "ifjuxhdz",  "status": "completed",  "number": 905396855192,  "code": "766892",  "message": "[Apple] Apple 766892",  "messages": [{ "text": "[Apple] Apple 766892", "code": "766892" }]}

Stop at a final status. Refunds are outcomes, not errors.

18 endpoints in three groups

The OpenAPI document is the contract. Anything it does not list is internal.

Sign in, check the token, or get a fresh one for the same session.

  • POST/auth/loginSign in
  • GET/auth/meCurrent user, checks the token
  • GET/auth/renewFresh token for the same session

Refetch, close and revise share one call per operation every 10 seconds.

Every order is an operation

Poll it while it is creating or pending. Each of the four final statuses is an answer, refunds included.

creating

Order accepted, a provider is being asked. Still creating after 30 minutes, it is refunded as stuck.

pending

A number is assigned and waits for its SMS. An accepted revise brings a completed operation back here.

completedfinal

The code arrived. Read number, code, message and messages[].

An accepted revise takes completed back to pending for another code on the same number.

When no code arrives, from creating or pending. Funds returned.

no_number_refundedfinal

No provider had a number.

system_refundedfinal

Ended without a code for another reason: a provider error, HidSim's account at a provider or its own systems, a live price outside your range, an expiry, a purchase that did not finish in time, or an operator.

user_refundedfinal

You closed or refunded it.

A refunded operation says why in refund.reason and when in refund.at.

  • no_number
  • price_out_of_range
  • supplier_unavailable
  • supplier_error
  • system_error
  • expired
  • canceled_by_you
  • stuck
  • operator

Treat an unknown reason like supplier_error.

Six rules that keep integrations working

  • Filter with _id.

    Relationship filters (_service, _country, _user, _countryIds) take Mongo _id values; path parameters take _id or the short id.

  • A purchase is not a delivery.

    A successful purchase means the operation exists. The SMS comes later.

  • Read code, not message.

    Use the structured code field; parse message only when you must.

  • Expect extra fields.

    Only documented fields are the contract. New ones can appear.

  • Skip products in cooldown.

    A product is out of stock while its cooldown.until is in the future. When every match is cooling, a service purchase answers 406 before anything is reserved; buying a product directly does not check it.

  • Check the token, not the catalog.

    Catalog reads answer even after a session ends. Call GET /auth/me: sign in again on 403, contact support on 423.

Errors, by status

Handle an error by its status first, then by its message. A 429 says how long to wait.

400
An invalid request, a business rule, or an action the operation's status does not allow.
401/403
Missing or invalid credentials, or a session that ended.
404
The resource does not exist.
406
Nothing matched the purchase, or the product, country or service is no longer sold.
423
The account is locked. Contact support.
425
Too early: a close before 4 minutes, or a revise before the code.
429
Rate limited. Wait for the Retry-After header (limiter.msBeforeNext in the body), then retry.
500+
A server-side failure. Retry with backoff.
{ "message": "balance.not_enough", "payload": {} }

Most errors answer with a message and a payload.

Start with the reference

Every request, parameter and response field of the 18 endpoints, in ReDoc and as OpenAPI JSON.

API referenceOpenAPI JSON

Base URL

https://a.hidsim.com

Planning volume? Tell support the services, countries and daily activations you expect.

Open a ticket