# eSIM API Overview

> Overview of the Roamify eSIM API services and the recommended steps to buy eSIMs, check your balance and more.

Canonical: https://docs.getroamify.com/esims/overview/

## Roamify eSIM Overview
Roamify eSIM API consists of the following services:

- [Countries](https://docs.getroamify.com/esims/countries/)
- [Packages](https://docs.getroamify.com/esims/packages/)
- [Orders](https://docs.getroamify.com/esims/orders/)
- [eSIMs](https://docs.getroamify.com/esims/esims/)
- [eSIM Events](https://docs.getroamify.com/esims/events/)
- [eSIMs Link](https://docs.getroamify.com/esims/esims-link/)
- [Vouchers](https://docs.getroamify.com/esims/vouchers/) (selected partners only)
- [Refunds](https://docs.getroamify.com/esims/refunds/)
- [Compatible Devices](https://docs.getroamify.com/esims/compatible-devices/)
- [Balance](https://docs.getroamify.com/esims/balance/)

You can use these services to buy eSIMs, check your balance, and more.

## Recommended steps to use eSIM API

Before implementing each step, review the endpoint-specific reference page for request and response schema details:
- [Countries](https://docs.getroamify.com/esims/countries/)
- [Packages](https://docs.getroamify.com/esims/packages/)
- [Orders](https://docs.getroamify.com/esims/orders/)
- [eSIMs](https://docs.getroamify.com/esims/esims/)
- [Events](https://docs.getroamify.com/esims/events/)
- [Balance](https://docs.getroamify.com/esims/balance/)

### Step 0: Flow Diagram
```mermaid
graph TD;
    subgraph Auth [Authentication]
        A[Step 1: Get Access Token]
    end
    subgraph Purchase [eSIM Purchase Flow]
        B[Step 2: Get eSIM Packages]
        C[Step 3: Submit eSIM Order]
        D[Step 4: Generate eSIM]
    end
    subgraph Usage [eSIM Usage & Management]
        E[Step 5: Get eSIM Usage]
        F[Step 6: Get Compatible Top-up Packages]
        G[Step 7: Top-up eSIM]
    end
    subgraph Account [Account Management]
        H[Step 8: Get Balance]
    end
    A --> B;
    B --> C;
    C --> D;
    D --> E;
    E --> F;
    F --> G;
    G -.-> E;
    A --> H;
```

### Step 1: Authentication
You need to have your Access Token to make requests to Roamify eSIM API. You can get your Access Token from [Roamify Partner Portal](https://partner.getroamify.com/sign-in).

If you don't have an account, you can sign up [here](https://partner.getroamify.com/sign-up) or contact us at [support@getroamify.com](mailto:support@getroamify.com).

Our token is a Bearer token, which means you need to include it in the `Authorization` header of your requests.

### Step 2: Get eSIM Packages
To get a list of eSIM packages, you need to send a `GET` request to the `/api/esim/packages` endpoint. 

This endpoint now returns paginated results. Use `page` and `pageSize` query parameters and iterate through pages when you need the full catalog.

Before filtering by country, fetch `GET /api/esim/countries` and use only these values:
- `country`: use the returned `name`
- `countryCode`: use the returned `code`

You can also filter packages by `geography`, `days`, `gbs`, and `isUnlimited`.

#### Usage - how to get eSIM packages
Here is an example of how you can get a list of eSIM packages using Roamify eSIM API.

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages?page=1&pageSize=50' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/packages?page=1&pageSize=50', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/packages/).

### Step 3: Submit an eSIM Order
To submit an eSIM order, you need to send a `POST` request to the `/api/esim/order` endpoint with the required body parameters.

The request body should contain the following parameters:
- `items`: An array of eSIMs you want to order. Each eSIM should contain the following details:
  - `packageId`: The ID of the eSIM package. This is a required field of type `string`.
  - `quantity`: The quantity of the eSIMs you want to order. This is a required field of type `number`.

Alternatively, you can send a `POST` request to the `/api/esim/order` endpoint using a previously provided `referenceId` in the request body.

#### Usage - how to create an eSIM order
Here is an example of how you can create an eSIM order using Roamify eSIM API.

**curl**

```bash
curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/order' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "items": [
        {
            "packageId": "Package ID",
            "quantity": 1
        }
    ]
}'
```

**javascript**

```javascript
const axios = require('axios');

axios.post('https://api-dev.getroamify.com/api/esim/order', {
    items: [
        {
            packageId: 'Package ID',
            quantity: 1
        }
    ]
}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/orders/).

### Step 4: Generate eSIM
As soon as you submit an eSIM order, in the response, you will get a dedicated `esimId` for each eSIM package you ordered. You can use this `esimId` to generate an eSIM, which will be ready to be used by your customers.

Alternatively, you can also use the `referenceId` you provided in the request body to generate an eSIM if applicable.

To generate an eSIM, you need to send a `POST` request to the `/api/esim/apply` endpoint with the required body parameters.

> **Warning:** `startDate` is required for packages where `requirements.travelDate` is `true`. Use ISO 8601 format (for example, `2026-07-01`).
> For full endpoint details, see [Generate eSIM Profile](https://roamify.apidog.io/generate-esim-profile-12947632e0).

The request body should contain the following parameters:
- `esimId`: The ID of the eSIM. This is a required field of type `string`.
- `referenceId`: The reference ID you provided when creating the order. This is an optional field of type `string`.
- `startDate`: Travel start date in ISO 8601 format. This is a conditional field required only when `requirements.travelDate` is `true`.

#### Usage - how to generate an eSIM profile
Here is an example of how you can apply an eSIM profile using Roamify eSIM API.

**curl**

```bash
curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/apply' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "esimId": "eSIM ID"
}'
```

**javascript**

```javascript
const axios = require('axios');

axios.post('https://api-dev.getroamify.com/api/esim/apply', {
    esimId: 'eSIM ID'
}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/esims/).

### Step 5: Get eSIM Usage
To get the usage details of an eSIM, you need to send a `GET` request to the `/api/esim/usage` endpoint with the required parameters.

The parameters required for this endpoint are:
- `iccid`: The ICCID of the eSIM. This is a required field of type `string`.

#### Usage - how to check eSIM usage
Here is an example of how you can get the usage details of an eSIM using Roamify eSIM API.

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/usage?iccid=ICCID' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/esim/usage?iccid=ICCID', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/esims/).

### Step 6: Get compatible top-up packages for an eSIM
Before you can top-up an eSIM, you need to know which packages are compatible with the eSIM you want to top-up. To get the compatible top-up packages for an eSIM, you need to send a `GET` request to the `/api/esim/topup/packages` endpoint with the required parameters.

For an end-to-end walkthrough (with decision points and diagram), see [Top-up Flow](https://docs.getroamify.com/esims/topup-flow/).

The parameters required for this endpoint are:
- `iccid`: The ICCID of the eSIM. This is a required field of type `string`.
- `days`: The number of days for which the eSIM package is valid. This is an optional field of type `number`.
- `gbs`: The amount of data in GB for which the eSIM package is valid. This is an optional field of type `number`.
- `isUnlimited`: The flag to indicate if the eSIM package is unlimited. This is an optional field of type `boolean`.
- `packageId`: The ID of the eSIM package. This is an optional field of type `string`.

#### Usage - fetch compatible top-ups
Here is an example of how you can get a list of compatible top-ups for an eSIM using Roamify eSIM API.

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/topup/packages?iccid=ICCID' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
    const axios = require('axios');

    axios.get('https://api-dev.getroamify.com/api/esim/topup/packages?iccid=ICCID', {
    headers: {
    'Authorization': 'Bearer {access token here}',
    'Content-Type': 'application/json'
}
})
    .then(response => {
    console.log(response.data);
})
    .catch(error => {
    console.error(error);
});
```

### Step 7: Top-up an eSIM
You may need to top-up an eSIM if the balance is low or the data limit is reached. To top-up an eSIM, you need to send a `POST` request to the `/api/esim/order/topup` endpoint with the required body parameters.

The request body should contain the following parameters:
- `iccid`: The ICCID of the eSIM you want to top-up. This is a required field of type `string`.
- `packageId`: The ID of the eSIM package you want to top-up. This is a required field of type `string`.

#### Usage - how to create a top-up order
Here is an example of how you can create a top-up order using Roamify eSIM API.

**curl**

```bash
curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/order/topup' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "iccid": "ICCID",
    "packageId": "Package ID"
}'
```

**javascript**

```javascript
const axios = require('axios');

axios.post('https://api-dev.getroamify.com/api/esim/order/topup', {
    iccid: 'ICCID',
    packageId: 'Package ID'
}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/orders/).

### Step 8: Get Balance
To get the remaining balance of your funds, you need to send a `GET` request to the `/api/balance` endpoint.

There are no required parameters for this endpoint.

#### Usage - how to check your balance
Here is an example of how you can get the remaining balance of your funds using Roamify eSIM API.

**curl**

```bash
curl --request GET \
--url 'https://api-dev.getroamify.com/api/balance' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'
```

**javascript**

```javascript
const axios = require('axios');

axios.get('https://api-dev.getroamify.com/api/balance', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
```

You can read more about this endpoint [here](https://docs.getroamify.com/esims/balance/).

### The End
That's it! You have successfully integrated Roamify eSIM API into your application. If you have any questions or need help, feel free to contact us at [support@getroamify.com](mailto:support@getroamify.com).