doctorSIM API v2

Integrate mobile top-ups and digital gift cards for 200+ countries and 1,600+ carriers into your application. This API powers the doctorSIM Agentic Commerce Platform for AI agents and developers.

Order Flows

Mobile top-ups and gift cards use the same authentication, credits, and order endpoints. The discovery steps differ; monitoring is identical for both.

Mobile top-up

Lookup phone number

Detect the carrier and country from an E.164 MSISDN before pricing.

GET /carriers/lookup/{phone}

Select airtime, data, or bundle

List service types, then pick a rate token for airtime, data, or bundle pricing.

GET /operators/{id}/service-types
GET /operators/{id}/rates

Order

Place the top-up with price_token and the recipient phone. Credits are deducted instantly.

POST /orders

Gift cards

Select country

Browse supported destinations and note the country ID or ISO code.

GET /countries

Search catalog

Find the gift card brand or product, then load rates and copy the token.

GET /products/search?country=
GET /operators/{id}/rates

Order

Place the gift card order with price_token. Some products omit a phone field.

POST /orders

Monitor (both)

Monitor delivery

Poll order status or register webhooks for async updates on top-ups and gift cards.

GET /orders/{id}
POST /webhooks

Authentication

All protected endpoints accept either API keys or OAuth 2.0 access tokens in the Authorization header.

API keys (server-to-server)

Best for backend integrations and the Explorer above. The Bearer token must contain a colon separating api_id and api_secret:

Authorization: Bearer {api_id}:{api_secret}

Log in to your PRO account, then create keys under My Account → API. The secret is shown only once — store it securely.

OAuth 2.0 (recommended for agents)

Available on this environment. Use dynamic client registration and authorization code + PKCE for interactive agents, or client credentials where supported.

Resource	URL
Authorization server metadata	https://www.doctorsim.com/.well-known/oauth-authorization-server
Register client	POST https://www.doctorsim.com/oauth/register
Authorize (PKCE)	GET https://www.doctorsim.com/oauth/authorize
Token exchange	POST https://www.doctorsim.com/oauth/token
Agent auth guide	https://www.doctorsim.com/auth.md

OAuth JWTs use a plain Bearer token (no colon). Scopes include orders:read, orders:write, balance:read, and webhook scopes — see the OpenAPI spec for details.

Environments

Both environments use the same host. The key prefix determines the mode:

Environment	Key prefix	Behavior
Sandbox	test_*	Orders stored in `api_sandbox_orders`; webhook cron simulates fulfillment (no credits, no Zendesk)
Production	live_*	Live transactions, credits deducted from your balance

Response Format

All responses follow a consistent envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123...",
    "timestamp": "2026-03-24T12:00:00Z"
  }
}

Error responses include an error object with a machine-readable code and human-readable message:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credit balance."
  },
  "meta": { ... }
}

Rate Limits

Tier	Requests/min	Headers
Free	50	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
Pro	500
Enterprise	5,000

Endpoint Reference

Countries & Operators

Discover supported destinations. Start here to find country IDs and operator IDs needed for pricing and orders.

Method	Path	Description
GET	/countries	List all supported countries with operator counts
GET	/operators?country=	List carriers for a country (e.g., Vodafone, Telcel)
GET	/operators/{id}/service-types	Service types for an operator (airtime, bundles, data)
GET	/service-types	All service type definitions

Products & Pricing

Search the catalog and get live pricing. Each rate includes a token — pass it as price_token when placing orders.

Method	Path	Description
GET	/operators/{id}/rates	Agent-friendly rate list with `token` per price point
GET	/products/search?country=	Catalog search with operator/service/image data
GET	/products/{operator_id}	Full operator detail with live pricing

Carrier Lookup

Detect the carrier from any phone number. Returns the operator ID needed for pricing and ordering.

Method	Path	Description
GET	/carriers/lookup/{phone}	Identify carrier from E.164 phone number

Orders

Create and track orders. Credits are deducted on order creation. Only read-write scoped keys can create orders.

Method	Path	Description
POST	/orders	Create a top-up or gift card order
GET	/orders	List completed orders (keyset pagination)
GET	/orders/{id}	Get single order status and details

Balance

Monitor your prepaid credit balance and transaction history.

Method	Path	Description
GET	/balance	Current credit balance (EUR)
GET	/balance/history	Recent credit transactions

Webhooks

Subscribe to order events. Max 5 webhooks per account. The signing secret is shown only once at creation.

Method	Path	Description
POST	/webhooks	Register a webhook (HTTPS only)
GET	/webhooks	List all webhooks
GET	/webhooks/{id}	Get webhook detail
PATCH	/webhooks/{id}	Update URL, events, or status
DEL	/webhooks/{id}	Delete a webhook

Events: order.created, order.fulfilled, order.failed

Sandbox vs. Production: Use sandbox keys (test_*) for safe integration testing — orders are stored in api_sandbox_orders and auto-fulfilled via the webhook cron (no credits, no Zendesk). Production keys (live_*) work in the Explorer too; mutating calls show a confirmation because they deduct credits and place real orders.

Select an endpoint

Choose an endpoint from the sidebar to see its parameters, execute it, and view the response. Enter your API credentials in the top bar to make live calls.