Bappy API

The Bappy API lets resellers and partners sell and manage eSIM and physical SIM data plans. Every card is a Link: you create a Link with a plan, top it up, follow its usage and send it SMS. Bappy takes care of billing and of provisioning with the mobile operator, so you integrate with one API instead of with each operator.


Base URL	`https://api.omaxtelecom.com/bappy/v1`
Authentication	Bearer access token — how to get one
Postman	Collection · Environment
AI assistants	Open in ChatGPT · Open in Claude · Markdown · MCP server

[!TIP] Try it here: enter your Client ID and Client Secret in the Authentication box, click Authorize, then use Test Request on any endpoint.

Who it is for:

Resellers — sell eSIM or SIM plans to end customers, for example for travel or M2M.
Integrators — add Link creation and top-up to your app, portal or booking flow.
M2M / IoT — create and manage Links from your own systems.

What you can do

Task	Endpoint	Description
Find a plan	`GET /plans`	Plans with price, data, validity and coverage
Check your balance	`GET /organization/balance`	Wallet balance used for Links and top-ups
Create a Link	`POST /links`	Activate an eSIM with a plan
List Links	`GET /links`	All your Links, with filters
Link details	`GET /links/{identifier}`	Usage, activations, eSIM install links, coverage
Top up	`GET /links/{identifier}/topup-plans`	Plans you can add to a Link
Link history	`GET /links/{identifier}/history`	Activations, top-ups, refunds and fees
Network status	`GET /links/{identifier}/network-status`	Where the card is connected right now
Send SMS	`POST /sms`	Send an SMS to a Link
Reports	`GET /transactions`, `/transactions/stats`, `/transactions/analytics`	Spending and usage reports
Health	`GET /health`, `GET /status`	Service availability (no token needed)

Quick start

Get credentials and a token — see Getting started.
Find a plan: GET /plans lists the available packages with price, data, validity and coverage.
Check your balance: GET /organization/balance. Creating a Link or topping up is paid from it.
Create a Link: POST /links with a plan_id. You get the Link UUID, ICCID, MSISDN, LPA profile and the eSIM install links.
Manage it: GET /links/{identifier} for details and usage, GET /links/{identifier}/topup-plans to add data.

Authentication

Send an access token on every request except GET /health and GET /status:

Authorization: Bearer <access_token>

Get the token from POST https://api.omaxtelecom.com/auth/token with your Console client_id and client_secret — not from Bappy itself. Getting started shows how, with code samples.

Your organization (tenant) comes from the token. Every Link, transaction, balance and SMS belongs to your organization only.

Links

A Link is one card — eSIM or physical SIM — and everything attached to it.

Property	Description
UUID	Unique identifier, assigned when the Link is created
ICCID	SIM card number, assigned by the provider
Status	`active`, `suspended` or `inactive`
Activations	The plans on the Link, each with its own usage, expiry and coverage

Every Link endpoint accepts either the UUID or the ICCID as {identifier}:

GET /links/550e8400-e29b-41d4-a716-446655440000 — by UUID
GET /links/8901010000000000001 — by ICCID

Creating a Link

POST /links with plan_id (and an optional name):

Your wallet balance is checked against the plan's retail price.
An available eSIM is reserved.
The price is taken from your wallet.
The plan is activated on the card.
The Link, its activation and the transaction are recorded.

If provisioning fails, the amount is refunded automatically.

Managing Links

List — GET /links, filtered by status or search, paged with page and per_page.
Details — GET /links/{identifier}: live usage, eSIM install links, all activations with their usage, and coverage.
Reactivate — PUT /links/{identifier} with {"status": "active"} turns a suspended Link back on.
Top-up plans — GET /links/{identifier}/topup-plans lists the plans that fit this Link, with data, validity, price and coverage.
Remove a plan — PUT /links/{identifier}/plans with {"remove": ["activation-uuid"]}. The activation IDs are in activations[].id of the Link details.
History — GET /links/{identifier}/history: activations, top-ups, refunds and monthly fees, newest first.
Network status — GET /links/{identifier}/network-status?live=true asks the network directly instead of using cached data.

eSIM installation

Creating a Link returns everything the end user needs to install the eSIM:

the LPA profile,
an Apple install link (iOS),
an Android install link.

GET /info/instructions returns step-by-step installation guides for iOS and Android that you can show your customers.

SMS to a Link

Send — POST /sms with link_id (UUID or ICCID) and message (up to 80 characters). The SMS is queued and delivered in the background.
List — GET /sms?link_id={identifier}.

Plans and coverage

List plans — GET /plans, filtered by region, coverage_type or sponsor_profile.
Plan details — GET /plans/{plan_id}.
Coverage — GET /plans/{plan_id}/coverage: every country with its operators and network types.
Regions — GET /plans/regions: EU, AF, AS, LA, NA, OC, for filtering plans.
Operators — GET /info/operators?search={country} finds mobile operators by country name.

Organization and reports

Profile — GET /organization: name, slug, status and your prices (price_per_sms, price_per_link).
Balance — GET /organization/balance: wallet balance and currency.
Transactions — GET /transactions, optionally for one link_id. For a single Link, GET /links/{identifier}/history is simpler.
Statistics — GET /transactions/stats for a from/to date range.
Analytics — GET /transactions/analytics for the last period_days, for example 30.

Responses

Success: { "success": true, "data": { ... }, "meta": { "timestamp", "response_time_ms" } }
Lists: data holds data (the items) and meta (current_page, last_page, per_page, total, from, to).
Errors: { "success": false, "error": { "code", "message", "details" }, "meta": { "timestamp" } }, with a matching HTTP status.

Bappy never exposes which mobile operator or provider is behind a Link. Provider problems are reported with generic codes such as PROVISIONING_ERROR or PROVIDER_UNAVAILABLE.

Billing

Your organization has one wallet. Creating a Link or topping it up is paid from it at the plan's retail price, and a failed provisioning is refunded automatically. Your SMS and Link prices (price_per_sms, price_per_link) are shown by GET /organization; monthly Link fees appear in the Link history.

Errors

Error code	HTTP status	What it means
`UNAUTHORIZED`	401	The token is missing or invalid — get a new one
`INSUFFICIENT_BALANCE`	402	Your wallet balance is too low
`ORG_SUSPENDED`	403	Your organization is suspended — contact support
`NOT_FOUND`	404	The resource does not exist
`PLAN_NOT_FOUND`	404	The plan does not exist or is not enabled for you
`VALIDATION_ERROR`	422	A request parameter is invalid
`INVALID_STATUS_CHANGE`	422	That status change is not allowed
`INVALID_STATE`	422	The resource is in a state that does not allow this
`INVALID_PLAN`	422	The plan cannot be used for this operation
`CONFIG_ERROR`	500	Server misconfiguration — contact support
`PROVISIONING_ERROR`	502	The provider returned an error
`PROVISIONING_FAILED`	502	The provider returned no result
`PROVIDER_ERROR`	502	The provider operation failed

Need help?

Email support@omaxtelecom.com. Tell us which endpoint you called, when, and what the response was — including its request_id if it has one. Never send your Client Secret or access token.