Partner-facing contract
18 documented endpoints
HidSim Partner API
Launch number-purchase automation without guessing how the platform works.
This is the public developer entry point for HidSim’s third-party API. Use it to authenticate, discover inventory, create asynchronous purchase operations, and retrieve SMS verification results through a partner-facing contract instead of internal routes.
Authentication
JWT Bearer
Fulfillment model
Asynchronous operations
Stable surface area
Build against a deliberately small contract instead of reverse-engineering internal resources or generic query behavior.
Fast catalog discovery
Move from country and service lookup to purchasable products without needing provider-specific logic in your client.
Operational clarity
Every order becomes an operation with explicit lifecycle states so fulfillment and refunds are straightforward to automate.
5-minute path
Go from credentials to SMS retrieval in one predictable flow.
The fastest successful integration is to authenticate once, discover inventory, create an order, and then poll the resulting operation until it reaches a terminal state.
1
Authenticate once
Log in with your partner credentials and reuse the returned JWT across protected calls.
POST/auth/login2
Discover inventory
List countries, search services, and fetch products for a specific service-country combination.
GET/countriesGET/services/searchGET/products3
Create an order
Purchase a specific product or let HidSim select inventory automatically within your price window.
POST/products/{productId}/purchasePOST/services/{serviceId}/purchase4
Poll the operation
Treat purchase as asynchronous and read number, code, and messages from the operation resource.
GET/operations/{operationId}Sample RequestLogin
curl -X POST "$API_URL/auth/login" \
-H "Content-Type: application/json" \
-d '{
"identifier": "[email protected]",
"password": "secret-password"
}'Sample PollOperation
curl "$API_URL/operations/$OPERATION_ID" \ -H "Authorization: Bearer $TOKEN"
Core resources
Authentication
Session management and token renewal.
- POST /auth/login
- GET /auth/me
- GET /auth/renew
Catalog
Country, service, and product discovery.
- GET /countries
- GET /services
- GET /services/search
- GET /products
Orders
Exact-product or automatic service-based purchase flows.
- POST /products/{productId}/purchase
- POST /services/{serviceId}/purchase
Operations
Poll, refetch, close, request another code, and manage asynchronous fulfillment.
- GET /operations/{operationId}
- GET /operations/{operationId}/refetch
- GET /operations/{operationId}/close
- GET /operations/{operationId}/revise
Contract rules
Use Mongo _id values for filters
For relationship fields such as _service, _country, _user, and _countryIds, use Mongo _id values. Path parameters accept _id and short id.
Treat purchase as asynchronous
A successful purchase response means the operation was created. It does not mean the SMS has already arrived.
Code beats message parsing
Use the structured code field whenever it is present. Avoid parsing the human-readable message field if you do not need to.
Build for additive responses
Only documented fields form the contract. Extra fields may appear and should not break your client.
Read why it was refunded
A refunded operation carries refund.reason (no_number, price_out_of_range, supplier_unavailable, supplier_error, system_error, expired, canceled_by_you, stuck or operator) and refund.at. system_error means HidSim’s own systems failed before any provider was asked; such refunds read supplier_error until 2026-10-12. Operations refunded before 2026-10-10 have none; treat an unknown reason like supplier_error.
Skip products in cooldown
A product a provider just had no number for carries cooldown.until, and the service purchase skips it until then: treat it as out of stock. When every match is cooling, the purchase answers 406 before anything is reserved.
Lifecycle
Model your client around operation states, not provider guesses.
Purchase endpoints create operations. Your system should keep polling until the operation reaches a terminal state and then stop. Refunded states are valid business outcomes, not transport failures.
creatingOrder accepted and provider work has started. Still creating 30 minutes later, it is refunded automatically (system_refunded, refund.reason stuck).
pendingNumber assigned and waiting for SMS or verification code. A completed operation comes back here after an accepted revise, keeping its messages[].
completedSMS received successfully. Use number, code, message, and messages[].
no_number_refundedNo number could be acquired: at least one provider tried had none, and none failed on HidSim's own account. Funds returned.
system_refundedEnded without a code for any other reason: a provider error, a live price outside your minPrice/maxPrice, an expiry, a purchase that did not finish in time, or an operator. Funds returned.
user_refundedOperation was closed or refunded after a user-triggered action.
Error handling
400Business rule failure, invalid request, or an action that is not valid in the operation’s current state.
401 / 403Missing, invalid, or expired credentials.
404Requested resource was not found.
406No products matched the purchase constraints for a service-based order.
425The requested operation action is too early: a close before its wait, or a revise before the code arrived.
429Rate limited. Back off and retry later.
Reference links
Keep the product page and the raw reference side by side.
Use this page for onboarding, lifecycle guidance, and architectural context. Use the API-hosted ReDoc reference when you need the raw endpoint contract and exact request or response shapes.