API Reference

Getting Started With Simtex Partners API

This page will help you get started with Simtex Partners API.

Simtex Partners API enables customers to manage the lifecycle of eSIM and Data roaming provisioning.

The API is a RESTful Web Service, uses JSON for both request and response.

👍

Getting Started

Use the Simtex Partners Portal to obtain an Api Key.

To obtain credentials for the Simtex Partners portal, please visit the Simtex website (click on "Book a meeting" to speak with our sales team).

Our first step is to set the account as a "sandbox", and when everything is ready according to your request, we will change it to a "live" account.

🔐

Authentication

The service uses Api Keys.

Api Keys should be added to all requests in the custom header 'X-Api-Key'.

General conventions

  1. Date/Time fields are represented as JSON strings in Iso-8601 format.
  2. Enum fields (e.g. eSIM Status) are represented as JSON strings.
  3. JSON responses may be extended without notice. Clients should be prepared to accept changes in the order of fields as well as in added fields.

An general overview of the API flow

  1. Get a new quote based on the destination countries and the duration of stay in each country.
    The response contains 3 different quotes with varying amounts of Quota GB.
  2. Place an order based on the chosen quote and obtain an eSIM.
  3. Provide the following eSIM functionality management:
  • Instructions for installation.
  • Status of data usage.
  • Top up a new package.

📘

eSIM functionality management can be operated by us by referring to the eSIM URL (optionally branded).

Actions

1. Placing a new Order

  1. Get a quote by providing destination countries and duration in each country. The response will provide multiple options - Basic data usage, Average data usage and High data usage. See here.
  2. Place an order for each of the passenger that requires an eSIM service. See here. Provisioning data will be returned.

2. Topping up an Existing eSIM

  1. Get a quote for the required eSim by using the eSIMId. See here. Multiple options will be returned.
  2. Place an order based on the quote. Provisioning data will be returned.

3. Viewing eSIM Status

Use the Get status action by using the eSIMId here.

4. Cancellation of eSIM

Cancellation is available so long as the eSIM has not been activated.

To cancel the service, use the Cancel action here.

🚧

We will only be able to cancel orders if the eSIM hasn't been installed, otherwise we won't be able to cancel orders.

5. Outbound Notifications

Webhooks and Callbacks will be sent in the events listed below.

The requests are posted by SImtex server to a Url specified by the customer in the Simtex Partners Portal. In case the Url is left empty, no notifications are sent.

In case of an issue to post a notification, the server will try to resend the message in increasing intervals for five more times during 32 minutes.

All such requests share a common field named 'messageType'. It should be used to detect the type of the message.

6. Usage Alert Webhook Notification

📘

Managing client alerts and notifications is possible with a webhook address. If there is no webhook address, we will send an email alert to the client (optionally branded).

When the system recognizes that the package data usage rate will be depleted before the package expiration date, an alert will be sent (webhook/end customer email address) that in X (hours) the data to X (destination) will be over.

The message model looks like:

{  
    "messageType": "UsageAlert"  
    "eSIMId": "GFRDz09R543nH9oP",  
    "countryCode": "US",  
    "timeDetected": "2023-01-31T15:23:32",  
    "alertLevelPercent": 75,  
    "dataAllocatedGB": 8.0,  
    "dataUsageGB": 6.7  
}

7. Order Cancellation Callback

Order cancellation may occur in two ways:

  1. Partner send a 'Cancel order' request.
  2. Customer visits the customers support and ask to cancel their eSIM Order.

In both cases, an 'OrderCancellation' callback will be triggered. See the 'Cancel order' Callback section.