{ "openapi": "3.0.3", "info": { "title": "SimBear Reseller API", "version": "1.0", "description": "Buy, deliver and manage anonymous data eSIMs from your own software. Human reference: https://simbear.io/reseller/" }, "servers": [ { "url": "https://simbear.io/reseller/v1" } ], "tags": [ { "name": "Service" }, { "name": "Account" }, { "name": "Catalogue" }, { "name": "Orders" }, { "name": "eSIMs" }, { "name": "Webhook" } ], "paths": { "/ping": { "get": { "tags": [ "Service" ], "summary": "Service check", "description": "Works without a key. With one, confirms that it is valid and returns the account id.", "operationId": "get_ping", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Service" ], "summary": "OpenAPI 3 document", "description": "Machine-readable version of this reference, for client generators and API tools.", "operationId": "get_openapi_json", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "tags": [ "Account" ], "summary": "Balance, discount and key details", "description": "The balance is what orders are paid from. Add funds (card or crypto) on the Billing page of the account that owns the key.", "operationId": "get_account", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactions": { "get": { "tags": [ "Account" ], "summary": "Balance ledger", "description": "Every movement on the balance: eSIM orders and top-ups (debit), balance top-ups and refunds (credit). Newest first.", "operationId": "get_transactions", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "1 to 200, default 50.", "schema": { "type": "integer" } } ] } }, "/locations": { "get": { "tags": [ "Catalogue" ], "summary": "Countries and regions with plans", "description": "Every destination that currently has at least one sellable plan, with the plan count and the cheapest price at your discount.", "operationId": "get_locations", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "country or region.", "schema": { "type": "string" } }, { "name": "popular", "in": "query", "required": false, "description": "1 for the popular destinations only.", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "required": false, "description": "Name or code search.", "schema": { "type": "string" } } ] } }, "/packages": { "get": { "tags": [ "Catalogue" ], "summary": "List plans", "description": "The full sellable catalogue, paginated. Filter by destination, plan type or text. Prices are at your discount; plans with validity.per_day true show the per-day price and take days on the order. Use updated_since to sync only what changed.", "operationId": "get_packages", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Location code from /locations, e.g. JP or EU-42.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO country code: that country's own plans plus every regional bundle covering it.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "fixed (a data bucket with a set validity), daily (a per-day allowance, you pick the days), unlimited (no data cap; some are per day, some have a set validity: see validity.per_day).", "schema": { "type": "string" } }, { "name": "topup_capable", "in": "query", "required": false, "description": "1 only plans that can be topped up, 0 only single-use plans.", "schema": { "type": "boolean" } }, { "name": "exclude_hk_exit", "in": "query", "required": false, "description": "1 to drop plans whose traffic exits through Hong Kong.", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "required": false, "description": "Text search on name and destination.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Unix time or ISO 8601: only plans changed since then.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "1 to 200, default 50.", "schema": { "type": "integer" } } ] } }, "/packages/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One plan", "description": "A single plan by id. For daily plans add ?days=N to get an exact quote.", "operationId": "get_packages_id_", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Package id from /packages.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Daily plans: number of days to quote.", "schema": { "type": "integer" } } ] } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Buy an eSIM", "description": "Charges the balance and orders the eSIM. 201: the eSIM exists and install details are in the response (status ready), or it is provisioning and will be ready within seconds. 202: the supplier has not confirmed yet; poll GET /orders/{id} or wait for the order.completed webhook. The reference makes the call idempotent: repeating it returns the same order (200) instead of buying twice.", "operationId": "post_orders", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "202": { "description": "Accepted, not confirmed yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package_id": { "type": "string", "description": "Package id from /packages." }, "days": { "type": "integer", "description": "Daily plans only: between validity.min_days and max_days." }, "reference": { "type": "string", "description": "Your own id for this order, up to 64 characters, unique per account." }, "quote_only": { "type": "boolean", "description": "true returns the price without buying." } }, "required": [ "package_id" ] } } } } }, "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "eSIM purchases and top-ups, newest first.", "operationId": "get_orders", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "processing, completed, failed or refunded.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "esim or topup.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "1 to 200.", "schema": { "type": "integer" } } ] } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "One order, with its eSIM", "description": "Poll this after a 202. status moves from processing to completed (esim present) or refunded (the money is back on the balance).", "operationId": "get_orders_id_", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id.", "schema": { "type": "integer" } } ] } }, "/esims": { "get": { "tags": [ "eSIMs" ], "summary": "List eSIMs", "description": "Every eSIM on the account, newest first.", "operationId": "get_esims", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "provisioning, ready, active, suspended, depleted, expired, cancelled or revoked.", "schema": { "type": "string" } }, { "name": "iccid", "in": "query", "required": false, "description": "Find by ICCID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "1 to 200.", "schema": { "type": "integer" } } ] } }, "/esims/{id}": { "get": { "tags": [ "eSIMs" ], "summary": "One eSIM", "description": "Status, usage and install details. A provisioning eSIM is refreshed from the supplier on every call; add ?refresh=1 to force a refresh otherwise.", "operationId": "get_esims_id_", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "required": false, "description": "1 to re-read status and usage from the supplier now.", "schema": { "type": "boolean" } } ] } }, "/esims/{id}/usage": { "get": { "tags": [ "eSIMs" ], "summary": "Usage", "description": "Data used and remaining. Refreshed from the supplier when older than 5 minutes (or with ?refresh=1). Unlimited plans report used bytes only.", "operationId": "get_esims_id_usage", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "required": false, "description": "1 to force a refresh.", "schema": { "type": "boolean" } } ] } }, "/esims/{id}/qr": { "get": { "tags": [ "eSIMs" ], "summary": "QR code (SVG)", "description": "The install QR code as an SVG image (image/svg+xml), encoding the LPA string. ?format=json returns {\"lpa\", \"svg\"} inside the usual envelope instead.", "operationId": "get_esims_id_qr", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "SVG image", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } }, { "name": "size", "in": "query", "required": false, "description": "Pixel size, 96 to 1024, default 256.", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "svg (default) or json.", "schema": { "type": "string" } } ] } }, "/esims/{id}/refresh": { "post": { "tags": [ "eSIMs" ], "summary": "Refresh from the supplier", "description": "Re-reads status, usage and install data upstream and returns the eSIM.", "operationId": "post_esims_id_refresh", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } } ] } }, "/esims/{id}/topups": { "get": { "tags": [ "eSIMs" ], "summary": "Available top-ups", "description": "Top-up options for this eSIM at your discount. Only for eSIMs with topup_capable true.", "operationId": "get_esims_id_topups", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } } ] }, "post": { "tags": [ "eSIMs" ], "summary": "Buy a top-up", "description": "Charges the balance and applies the top-up. 201 with the order and the grown eSIM. If the supplier rejects it nothing is charged (502 provider_error). reference works as for orders.", "operationId": "post_esims_id_topups", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "202": { "description": "Accepted, not confirmed yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topup_id": { "type": "string", "description": "Top-up id from GET /esims/{id}/topups." }, "reference": { "type": "string", "description": "Your own id, unique per account." } }, "required": [ "topup_id" ] } } } } } }, "/esims/{id}/cancel": { "post": { "tags": [ "eSIMs" ], "summary": "Cancel an unused eSIM", "description": "Only eSIMs that were never installed (status ready, cancellable true). The purchase price returns to the balance.", "operationId": "post_esims_id_cancel", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "eSIM id, e.g. ESM-5D38FE28", "schema": { "type": "string" } } ] } }, "/webhook": { "get": { "tags": [ "Webhook" ], "summary": "Current webhook", "description": "The URL this key delivers events to, if any.", "operationId": "get_webhook", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Webhook" ], "summary": "Set the webhook URL", "description": "Public http(s) URL. Returns a new signing secret: store it, it is shown once. Setting a URL again rotates the secret.", "operationId": "put_webhook", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Where to POST events." } }, "required": [ "url" ] } } } } }, "delete": { "tags": [ "Webhook" ], "summary": "Remove the webhook", "description": "Stops deliveries for this key.", "operationId": "delete_webhook", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/test": { "post": { "tags": [ "Webhook" ], "summary": "Send a ping event", "description": "Queues a ping event, delivered within a minute.", "operationId": "post_webhook_test", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/deliveries": { "get": { "tags": [ "Webhook" ], "summary": "Recent deliveries", "description": "The last 50 events with attempt counts and the last response.", "operationId": "get_webhook_deliveries", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer sb_live_..." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Envelope": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "description": "The resource or list, see the human reference for each endpoint." }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } } }, "required": [ "ok", "data" ] }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "insufficient_balance", "package_not_found", "esim_not_found", "order_not_found", "topup_not_found", "not_found", "reference_conflict", "order_refunded", "esim_not_cancellable", "not_ready", "no_webhook", "invalid_parameter", "topup_not_supported", "cancel_not_supported", "invalid_webhook_url", "invalid_json", "rate_limited", "provider_unavailable", "provider_error", "order_failed", "internal_error" ] }, "message": { "type": "string" }, "details": [] }, "required": [ "code", "message" ] } }, "required": [ "ok", "error" ] } } } }