Introduction

Dig into our API reference documentation and quickstarts. esimba.ai API documentation provides instructions on where to find API keys to access esimba.ai API. You’re covered with everything from the query structure and API requests with detailed explanations on receiving lists of lines and bundles that belong to your Partner Account.

esimba.ai API is a primary way to get data in and out of the esimba.ai Console. You can use esimba.ai API to control your account, view balance reports, receive a list of lines that belong to your Partner Account, change line status, receive usage data, refill lines, etc.

Overview

We have designed the esimba.ai API in a RESTful way to ensure smooth communication between the client (frontend) and the server (backend). Anytime you request a server using a REST API, you receive responses via HTTP functions described in this documentation.

What is REST API?

API stands for “Application Programming Interface.” It’s a set of rules enabling programs to talk to each other, exposing data and functionality across the Internet in a consistent format.

REST stands for “Representational State Transfer.” This architectural pattern describes how distributed systems can expose a consistent interface. When people use the term ‘REST API,’ they generally refer to an API accessed using the HTTPS protocol at a predefined set of URLs.

These URLs represent various resources — any information or content accessed at that location. Often resources have one or more methods that can be performed over HTTPS. At esimba.ai, we use GET, POST, and PUT methods.

• GET is used to retrieve resources,
• POST - to create resources,
• PUT - to update resources.

Connection

esimba.ai REST API is a server over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

HTTPS uses TLS (SSL) to encrypt normal HTTP requests and responses and digitally sign those requests and responses.

HTTPS is far more secure than HTTP.

Timestamps

The server time zone is UTC.

There must be consistency across all date-related data. All requests to a server must be aligned to UTC hour boundaries.

Countries

All country entries are in ISO 3166-1 alpha-2 format.

The purpose of ISO 3166 is to define internationally recognized codes of letters and/or numbers that we can use when we refer to countries and their subdivisions.

Currency

USD is the default and the only allowed currency.

Media types

All data is sent upon a user submitting GET/POST/PUT requests with parameters through the requested URL.

Authentication

esimba.ai authenticates your API requests using your account’s API keys representing the required credentials.

Each request has to include API Credentials

Example:

curl -X GET "https://{your_link}/api/v2/lines?per_page=3&page=2" -H "apiKey: Your_apiKey" -H "accessToken: Your_accessToken"

You can find the API Keys under “API Credentials” in your account (see the image below).

If you cannot find your API Keys, please contact your Personal Manager.

Implement the following security measures to ensure the privacy and security of your users’ eSIM data when using esimba.ai API.

Each API request has to include API credentials, such as apiKey and accessToken, that you can find in your account. Don’t share this information with anyone. We don’t save any payment information from users. All API requests should use HTTPS URLs only.

Use standard security measures: Keep passwords/keys safe and only request API via HTTPS.

API Commands Usage

Consider the following example demonstrating API Commands usage for eSIM purchase.

• A user selects a country within the partner’s app or platform and receives a list of bundles through the /bundles command.
• They browse the eSIM bundles, select the desired bundles, and proceed to payment.
• After a successful payment, the line is created using the /line/create command. The partner receives the payment, and funds are deducted from the account balance.
• For eSIM installation, the user receives the LPA code (via the same API command), which can be transformed into a QR code.

*The visuals presented in the document are just one example of the development of API commands. The actual implementation may vary depending on the partner’s specific requirements.

eSIM Device Compatibility Check

You can offer users the option of checking that their device supports eSIM technology before purchasing an eSIM line to avoid installation issues. This is not mandatory but rather advised. /esim_enabled_devices API command offers an up-to-date list of eSIM-enabled devices that partners can display on their platform.

• Users can refill their line with additional data amounts when they exhaust their available data. The available refills can be seen through the command /line/{ICCID}/available_refills. Although in most cases, they are standardized.
• Users can activate the Auto-refill feature to ensure they never run out of balance. It automatically adds data to their line when it falls below 100 MB or when the data validity expires. /line/{ICCID}/turn_on_auto_refill. command operates similarly to line creation or refilling: the chosen refill is automatically added to the specific line (via ICCID).

Integration Process

For a streamlined integration of the esimba.ai API, it is recommended to develop an integration module incorporating key API commands:

• /lines
• /line/{iccid}/get_details
• /line/{iccid}/available_refills
• /line/create
• /line/{iccid}/refill

This list encompasses essential commands to begin implementation. Additional API commands, though optional, can provide users with supplementary information.

Detailed descriptions of each command and comprehensive information can be found in the API documentation below.

It is advised to have an independent backend to handle requests to the esimba.ai API. Direct client application requests are discouraged to prevent exposure of the partner key.

The recommended scheme involves routing requests: mobile application >> partner API >> esimba.ai API.

If you use our Payment Gateway, you must integrate Stripe into your application and use the /get_pay_intend request for each API call.

Organizations employing payment chains must confirm payment completion before submitting /line/create and /line/{iccid}/refill requests to us.

Activation following purchase or refill is automatic; no further activation steps are required.

Making requests

Please use HTTPS requests because it’s more secure than HTTP.

HTTP Methods

Permitted HTTP methods are:

Rate limit

All calls within the esimba.ai API are allotted a specific number of requests per refresh period. Each API request returns the following header information regarding rate limits and the number of requests left.

Depending on the endpoint you are trying to reach, it will have a specific number of allowed requests per refresh period.

Currently, we have a default API limit of 60 requests per minute. The number of remaining requests can be found in the response header named X-RateLimit-Remaining (see image above).

Status and error codes

Sometimes, your API call may generate an error. Here you will find additional information about what to expect if you don’t format your request correctly or if we fail to process your request properly.

• 200 OK: The request was successful.
• 401 UNAUTHORIZED: The supplied credentials are insufficient to access the resource.
• 403 FORBIDDEN: The response status code indicates that the server understands the request but refuses to authorize it.
• 404 NOT FOUND: Resource was not found.
• 405 METHOD NOT ALLOWED: Resource can not be accessed with this method (GET, POST, etc.)
• 500 SERVER ERROR: Representation could not be returned due to an internal server error
• 503 SERVICE UNAVAILABLE: Representation can not be returned due to a temporary service outage.

Formatting Your Request

Accept Header

The API provides JSON responses and requires the accept header. The API uses application/json.

Request Body

When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

Examples:

GET

POST

PUT

Pagination

You can get paginated results (e.g., you can get the first 25 elements, the second 25 elements, etc.). All details can be found in the request section.

Below is a basic example of sending a request to get paginated results.

Successful Requests

Below is a general overview of what resource objects return with successful API requests.

Webhooks

Webhooks are a convenient way to keep track of line usage and changes in the status of your esimba.ai lines.

You can subscribe to events for your products and payments by activating webhooks that will push notifications to a given URL.

We use HTTPS to send notifications about selected events.

Here is how esimba.ai webhooks work:

• The partner can choose events about which webhooks will be sent;
• When certain events occur, webhooks are sent to the partner;
• Data in webhooks of different events is different;
• The partner can specify the URL to which webhooks will be sent to respond to changes;
• The partner can change the URL to which webhooks will be sent;
• The partner can remove the URL to which webhooks were sent to stop receiving them;
• The partner can view the entire list of webhooks sent to them and their responses;
• A webhook is considered delivered if it receives status 200 in response;
• The undelivered webhook is not resubmitted.

Webhook Signature Verification

To ensure the authenticity of incoming webhook requests, each payload includes a cryptographic signature in the X-Keepgo-Signature header. You can validate this signature to confirm the request originates from Keepgo.

Set Secret Key

At myaccount, in the User Profile menu, choose Webhooks > Create a Secret Key.

Signature Header

The server sends the signature in the X-Keepgo-Signature header.

Example (Http):

X-Keepgo-Signature: "abc123...xyz456" 

Signature Generation

The signature is computed as (PHP):

$signature = base64_encode(hash_hmac("sha256", $rawPayload, $secretKey, true));

Where:
$rawPayload = Raw request body (JSON string).
$secretKey = Your webhook`s secret key (provided during setup).

Verification Steps

1. Extract the X-Keepgo-Signature from the request headers.
2. Recompute the signature using the received payload and your secret key.
3. Compare the computed signature with the header value. If they match, the request is valid.

Example (PHP):

$receivedSignature = $_SERVER["HTTP_X_KEEPGO_SIGNATURE"];
$rawPayload = file_get_contents("php://input"); // Raw JSON body
$secretKey = "xxxxxxxxxxx"; // Your secret key here, should be kept secure
$signature = base64_encode(hash_hmac("sha256", $rawPayload, $secretKey, true));
if (hash_equals($receivedSignature, $signature)) {
  // Valid request
}
    

Steps to receive webhooks

You can start receiving event notifications using the steps described below.

• 1. Specify the URL to which webhooks will be sent.

  You can enable/disable and change URL for webhooks in your Partner Account.

  Please contact your Personal Manager if you need help with the webhooks setup.

• 2. Select the events you want to be notified about.

  The webhook events we currently support are listed in the table below.

  Name	Description
  simcard.usage.changed	Occurs when the Line’s usage changes.
  stripe.paymentIntent.succeeded	Partners who’ve integrated esimba.ai Payment Gateway can use this webhook event to receive notifications when the status of PaymentIntent changes.
  simcard.usage.low_data	Occurs when the Line’s usage equals or falls below 100 MB.
  bundle.added	Occurs when a bundle is added to the platform.
  bundle.removed	Occurs when a bundle is removed from the platform.
  simcard.status.changed	Occurs when the Line’s status is changed.

  simcard.usage.changed webhook example:

  {
    "event": "simcard.usage.changed",
    "timestamp": "2025-06-09T07:36:09.618973Z",
    "data":
    {
      "iccid": "12345678902116678",
      "deactivation_date": "",
      "allowed_usage_kb": 1048576,
      "remaining_usage_kb": 1048576,
      "remaining_days": null,
      "remaining_voice_seconds": null,
      "remaining_sms_count": null,
      "status": "Registered",
      "data_bundles": [
        {
            "id": 14,
            "status": "Non-active",
            "allowed_usage_kb": 1048576,
            "active_kb": 0,
            "remaining_usage_kb": 1048576,
            "allowed_voice_seconds": 3600,
            "active_voice_seconds": 0,
            "remaining_voice_seconds": 3600,
            "allowed_sms_count": 50,
            "active_sms_count": 0,
            "remaining_sms_count": 50,
            "validity": 7,
            "assigned_at": "2022-09-22 23:17:27",
            "activated_at": null,
            "terminated_at": null,
            "expire_at": null
        }
      ]
    }
  }
  

  simcard.usage.low_data webhook example:

  {
    "event": "simcard.usage.low_data",
    "timestamp": "2025-06-09T07:36:09.618973Z",
    "data":
    {
      "iccid": "12345678902116678",
      "user_email": "some-email@example.com",
      "remaining_data_mb": 90.23,
      "remaining_mb_threshold": 100
    }
  }
  

  Notes:

  • The user_email field is optional and may not be present.
  • It appears only if the SIM line is assigned to an end user.
  • This is the end user’s email address, not the partner’s.

  bundle.added webhook example:

  {
    "event": "bundle.added",
    "timestamp": "2025-06-09T06:55:15.069936Z",
    "data": {
      "bundle": {
          "id": 352,
          "name": "Octans",
          "description": "LATAM eSIM: 17 countries, Claro coverage in most places",
          "bundle_type": "regional",
          "coverage": [
              "Argentina",
              ...,
              "Uruguay"
          ],
          "refills": [
              {
                  "title": "1 GB",
                  "amount_mb": 1024,
                  "voice_minutes": null,
                  "sms_count": null,
                  "price_usd": 28
              },
              ...,
              {
                  "title": "50 GB",
                  "amount_mb": 51200,
                  "voice_minutes": null,
                  "sms_count": null,
                  "price_usd": 725
              },
          ],
          "privacy_ip": "Netherlands",
          "networks": [
              {
                  "title": "Argentina",
                  "local_networks": [
                      "Claro"
                  ],
                  "flag": "https://{your_link}/img/flags/3x2/ar.svg"
              },
              ...,
              {
                  "title": "Uruguay",
                  "local_networks": [
                      "Claro"
                  ],
                  "flag": "https://{your_link}/img/flags/3x2/uy.svg"
              }
          ],
          "kyc_required": false
      }
    }
  }
  

  bundle.removed webhook example:

  {
    "event": "bundle.removed",
    "timestamp": "2025-06-09T06:55:15.069936Z",
    "data": {
      "bundle": {
          "id": 352,
          "name": "Octans",
          "description": "LATAM eSIM: 17 countries, Claro coverage in most places",
          "bundle_type": "regional",
          "coverage": [
              "Argentina",
              ...,
              "Uruguay"
          ],
          "refills": [
              {
                  "title": "1 GB",
                  "amount_mb": 1024,
                  "voice_minutes": null,
                  "sms_count": null,
                  "price_usd": 28
              },
              ...,
              {
                  "title": "50 GB",
                  "amount_mb": 51200,
                  "voice_minutes": null,
                  "sms_count": null,
                  "price_usd": 725
              },
          ],
          "privacy_ip": "Netherlands",
          "networks": [
              {
                  "title": "Argentina",
                  "local_networks": [
                      "Claro"
                  ],
                  "flag": "https://{your_link}/img/flags/3x2/ar.svg"
              },
              ...,
              {
                  "title": "Uruguay",
                  "local_networks": [
                      "Claro"
                  ],
                  "flag": "https://{your_link}/img/flags/3x2/uy.svg"
              }
          ],
          "kyc_required": false
      }
    }
  }
  

  simcard.status.changed webhook example:

  {
      "event": "simcard.status.changed",
      "timestamp": "2025-10-06T08:55:19.329856Z",
      "data": {
        "iccid": "12345678902116678",
        "oldStatus": "Registered",
        "currentStatus": "Activated"
      }
    }
  

• 3. Receive a response object.

  Your Webhook URL should return a response with HTTP status code 200. Any other HTTP response code will be treated as a failure.

Sandbox

The sandbox is a separate environment for building and testing your integration without real money, real lines or real mobile operators. It runs the same API as production, so the code you write against the sandbox works in production unchanged — only the address and the API credentials differ.

Getting started

• Sandbox console: https://myaccount.sandbox.keepgo.com
• Sandbox API: https://myaccount.sandbox.keepgo.com/api/v2

Register a partner account at https://myaccount.sandbox.keepgo.com/partner/register and take the API Key and Access Token from “API Credentials” in the sandbox console. Production credentials do not work in the sandbox, and sandbox credentials do not work in production.

A new sandbox account comes with a test balance, so you can buy lines and refills right away.

How the sandbox differs from production

• Lines are not real. ICCIDs, activation codes and QR codes are generated by the sandbox. A sandbox eSIM profile cannot be installed on a device.
• The catalogue is a copy of production. Bundles, countries and regions are the same as in production. Line stock is replenished every hour, so an “out of stock” answer can still happen and is worth handling.
• Operator answers come with a delay. The mobile operator is simulated and answers a few seconds (about 5) after a line is created or refilled, so a new package is first reported as “Configuring” and becomes available after that.
• Traffic is not spent on its own. Nobody uses sandbox lines, so data usage appears only when you simulate it with the request described below.
• Webhooks are delivered. Set a webhook URL in the sandbox console to receive events exactly as in production.
• Nothing else leaves the sandbox. Emails and push notifications are not sent. SMS and other commands addressed to the operator are accepted but have no effect.

Simulating data usage

This request exists only in the sandbox. In production the same path returns 404.

POST /api/v2/sandbox/line/{iccid}/simulate_usage

Spends data on one of your sandbox lines as if the line had been used. The line changes the way it would after real traffic — the package becomes active and its remaining data goes down — and the same usage webhooks as for real traffic are sent (for example, simcard.usage.changed).

Authentication: the same apiKey and accessToken headers as every other request.

Path parameter:

• iccid (string, required) — ICCID of a line that belongs to your account.

Request body (JSON):

• used_mb (integer, required) — how much data to spend, in megabytes, from 1 to 1048576.

Example:

curl -L -X POST "https://myaccount.sandbox.keepgo.com/api/v2/sandbox/line/8910300000000000001/simulate_usage" \
  -H "apiKey: Your_apiKey" \
  -H "accessToken: Your_accessToken" \
  -H "Content-Type: application/json" \
  -d '{"used_mb": 500}'

Responses:

200 — the data was spent. used_mb is how much was actually taken off the line:

{
  "ack": "success",
  "used_mb": 500
}

On a travel line packages are used up one after another, and no more can be spent than the line has left, so used_mb can be smaller than requested. On a Lifetime line the whole requested amount is spent.

400 — used_mb is missing or out of range, or the line is not found or does not belong to your account. reason says which:

{
  "ack": "fail",
  "reason": "SIM card not found"
}

401 — the API credentials are missing or wrong.