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, and manage asynchronous fulfillment.
- GET /operations/{operationId}
- GET /operations/{operationId}/refetch
- GET /operations/{operationId}/close
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.
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.
pendingNumber assigned and waiting for SMS or verification code.
completedSMS received successfully. Use number, code, message, and messages[].
no_number_refundedNo suitable inventory could be assigned and funds were returned.
system_refundedProvider or fulfillment failure with 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, commonly close.
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.