Order your first eSIM

By the end of this guide you’ll be able to use the eSIM Go API to supply your end users with a QR code for their new eSIM and data bundle.

First though, you’ll learn how to test that the ordering process is working.

We will use five steps to provide our user with a new eSIM and data bundle:

1. Add a bundle to your inventory.
2. Apply a data bundle to a new eSIM.
3. Download QR Codes
4. User installs the eSIM on a compatible device.
5. Check the status of the a bundle assigned to an eSIM.

How it works

Just like plastic SIMs, the mobile data bundles which your users buy are applied to eSIMs, which are either already installed on a device, or can be downloaded and installed, using a QR Code.

In effect, the eSIM is a user account provided by the Mobile Network Operator (MNO). We identify this eSIM with an ICCID (Integrated Circuit Card Identifier).

This account can then be assigned access to network privileges. These are what we call ‘bundles’. For example, (1GB) for a specific period (7 Days), in a certain country (AD). This gives you the bundle name, such as esim_1GB_7D_AD_U

Setting up a test account

We advise that you set up a secondary account which you can use to test your processes.

When creating this second account, please add UAT to the end of your Organisation name.

This will provide you with an alternate Portal and API Key, allowing you to test all processes and API calls, without touching your live environment.

The /orders endpoint can be tested by keeping "type": "validate" in the request. This will allow you to test the eSIM ordering process, without reducing your credit balance.

Before you start: Test the eSIM bundle ordering process

When ordering a bundle via the API, you have the option to test if the order will be successful before you commit to the purchase.

Make sure you have located and entered your API Key. This is needed for authentication purposes.

1. Open the API Orders endpoint documentation in a new window

2. Find the REQUEST BODY section, abut half way down the page

3. Click EXAMPLE

   

4. Enter quantity of bundle required - in this example, “5”

5. Set item to the name of your chosen bundle. In this example we used esim_1GB_7D_GB_U

Names of bundles are case sensitive and can be found in the API catalogue

6. Click ‘Try’ and you should see a RESPONSE similar to the one shown below

If the transaction was valid, you’ll see total value in the RESPONSE.

If the transaction failed you’ll see an error message detailing the issue.

Once you’re happy that the process is working as it should, you can Create an eSIM using the API.

Order an eSIM using the API

When a customer orders a particular data bundle, (for example, 5GB, for 30 Days, in France) they may or may not already have an eSIM able to accept this bundle as a top-up.

If they don’t have a suitable eSIM, you’ll need to create and assign one for them. This can be accomplished through the API or the portal. Here we’ll cover the API process.

QR Codes

When creating a new eSIM using the API you have the ability to do so by either generating your own QR code, or using the eSIM Go API to download a generic QR code. For simplicity, we’ll just cover the generic case here. See our help pages for how to create branded QR codes.

1. Add a bundle to your inventory

Order the required bundle using /orders endpoint: https://docs.esim-go.com/api/#post-/orders

• Click ‘EXAMPLE’ in the ‘REQUEST BODY’ section of the page
• Set "type" to "transaction"
• Set "assign" to "true"
• Enter "quantity" of bundle required - this example uses 1
• In "item" enter the name of the bundle. This example uses "esim_1GB_7D_AD_U"
• Click ‘Try’

• If you have a successful transaction then you will see in the ‘RESPONSE’ section: "statusMessage": "Order completed" along with the number of eSims assigned.
• You will use the orderReference value to download your QR codes later.

2. Apply a bundle to a new eSIM

We will auto-assign a bundle from our inventory to a new eSIM (iccid), using the /esims/apply endpoint: https://legacy-docs.esim-go.com/api/#post-/esims/apply 

• Click ‘EXAMPLE’ in the ‘REQUEST BODY’ section of the page
• Set “name” to the bundle you want to assign to the new eSIM
• The example below uses "name": "esim_1GB_7D_AD_U”

• Click ‘TRY’. If you have a successful transaction, you should see:
  • "status": "Successfully Applied Bundle"
  • The ICCID of the SIM the bundle has been applied to
  • The “applyReference”

A successful RESPONSE is shown below:

3. Download installation QR Codes

You can download the QR Code as a .png, or as a .zip if you have multiple eSIMs.

For this, use the /esims/assignments endpoint:  https://legacy-docs.esim-go.com/api/#get-/esims/assignments

• Find the orderReference value generated in step 1, or the applyRefence from step 2
• Use this as the query parameter for a GET request to the /esims/assignments endpoint.
• Set the Accept header to request application/zip
• The return value will be a .zip file containing QR code images in .png format

4. User installs the eSIM

Now, your user can use the QR Code you generated in step 3 to install their eSIM.

Read our article on how to install a new eSIM.

5. Check the status of a bundle assigned to an eSIM

Now we can use the /esims/{iccid}/bundles/{name} endpoint to see what’s happening with our user’s bundle.

This will tell us whether a bundle has begun to be used and how much data is left to be consumed.

• In the PATH PARAMETERS fields of the REQUEST section, input your iccid and bundle name. You should have something like the example below, with your previously obtained iccid and bundle name.

• Click ‘TRY’

You should see a RESPONSE something like the example below:

• bundleState can be:

   processing,queued, active, depleted, expired, revoked

• remainingQuantity gives the unused amount of data in bytes