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.

MCP Server

AI agents can connect via the MCP Server guide using OAuth + PKCE. PRO accounts debit prepaid credits on POST /orders. Regular OAuth users receive a payment_link (hash checkout on doctorsim.com) and get an order_id only after payment.

Order Flows

Mobile top-ups and gift cards share authentication and order endpoints. PRO checkout uses credits; consumer OAuth uses payment links. Always call POST /orders/preview before POST /orders.

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). PRO: scopes include orders:read, orders:write, balance:read, and webhooks. Consumer OAuth: orders:read and orders:write only (no balance or webhooks).

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 plus service_fee_eur/usd and total_cost_eur/usd per price point. Pass the token as price_token in preview and order calls; use POST /orders/preview for the authoritative full breakdown (including optional SMS fee).

Method	Path	Description
GET	/operators/{id}/rates	Agent-friendly rate list with token, service fee, and total 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

Preview pricing, create orders, and track delivery. POST /orders/preview returns the exact account-specific breakdown (recharge, service fee, optional 0.99 EUR SMS fee, total, credit applied) without placing an order — requires read scope. Credits are deducted only on POST /orders (requires read-write / orders:write).

Method	Path	Description
POST	/orders/preview	Preview exact price breakdown; same body as create order, no credits deducted
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