Roamify eSIM API

https://docs.getroamify.com
Admin
Roamify eSIM API is a RESTful API that enables travel businesses to integrate eSIM services,...
Tokens:18,715
Snippets:78
Trust Score:8.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Fetch eSIM Compatible Devices API Usage Examples

Source: https://docs.getroamify.com/esims/compatible-devices

Provides code examples in cURL and JavaScript for making a GET request to the `/api/compatible-devices` endpoint to retrieve a list of compatible devices from the Roamify eSIM API. Both examples demonstrate how to include the necessary Authorization and Content-Type headers.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/compatible-devices' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Get All eSIM Packages Example

Source: https://docs.getroamify.com/esims/packages

Demonstrates how to make a GET request to the Roamify eSIM API to retrieve all available eSIM packages without any filters. Examples are provided for both curl and JavaScript using Axios.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Roamify Affiliate API Get Packages Response Schema and Example

Source: https://docs.getroamify.com/affiliate/affiliate-links

This entry describes the structure of the successful JSON response from the Roamify Affiliate API when retrieving eSIM packages. It details the top-level `packages` array, `countryName`, nested `packages` array within each country, and the `link` field, followed by a comprehensive example of the full JSON payload.

```APIDOC
Response Body Structure:

Root Object:
  - "status": string (e.g., "success") - Indicates the status of the API call.
  - "data": object - Contains the primary response payload.
    - "packages": array of country objects - The top-level response data containing an array of packages for each country.
      - Each country object contains:
        - "id": string (UUID) - Unique identifier for the country entry.
        - "countryName": string - The name of the country (e.g., "Afghanistan").
        - "countryCode": string - The two-letter country code (e.g., "AF").
        - "region": string - The geographical region (e.g., "local").
        - "packages": array of package objects - For each country object, an array of eSIM packages available for that destination.
          - Each package object contains:
            - "id": string (UUID) - Unique identifier for the package.
            - "name": string - Display name of the package (e.g., "1 GB - 7 Days").
            - "price": number (float) - Price of the package.
            - "validity": number (days) - Duration the package is valid for.
            - "plan": string - Type of plan (e.g., "data-only").
            - "dataAmount": number (MB) - Total data amount in MB.
            - "dataUnit": string - Unit for dataAmount (e.g., "MB").
            - "data": string - Formatted data amount (e.g., "1 GB").
            - "isUnlimited": boolean - True if data is unlimited.
            - "isActivated": boolean - True if the package is active.
            - "withKyc": boolean - True if KYC is required.
            - "withTopUp": boolean - True if top-up is available.
            - "withSMS": boolean - True if SMS is included.
            - "withCall": boolean - True if calls are included.
            - "withHotspot": boolean - True if hotspot is allowed.
            - "smsUnit": string - Unit for SMS amount.
            - "callUnit": string - Unit for call amount.
            - "smsLabel": string - Label for SMS.
            - "callLabel": string - Label for calls.
            - "smsAmount": number - Amount of SMS included (-1 if unlimited/not applicable).
            - "callAmount": number - Amount of calls included (-1 if unlimited/not applicable).
            - "coverages": array of strings - Countries covered by the package.
            - "networks": array of strings - Network technologies supported (e.g., "3G", "4G").
            - "signals": array of signal objects - Detailed network signal information.
              - Each signal object contains:
                - "code": string - Country code.
                - "name": string - Country name.
                - "networks": array of strings - Supported networks in this country.
                - "carriers": array of strings - Supported carriers in this country.
            - "link": string (URL) - The referral link for the package, which includes your unique identifier.
```

```json
{
	"status": "success",
	"data": {
		"packages": [
			{
				"id": "c21a8a20-5646-4b26-8df3-f5d37147790f",
				"countryName": "Afghanistan",
				"countryCode": "AF",
				"region": "local",
				"packages": [
					{
						"id": "515e279d-0c78-4d65-a45b-e7c12ca2ebea",
						"name": "1 GB - 7 Days",
						"price": 5.5,
						"validity": 7,
						"plan": "data-only",
						"dataAmount": 1024,
						"dataUnit": "MB",
						"data": "1 GB",
						"isUnlimited": false,
						"isActivated": true,
						"withKyc": false,
						"withTopUp": true,
						"withSMS": false,
						"withCall": false,
						"withHotspot": true,
						"smsUnit": "",
						"callUnit": "",
						"smsLabel": "",
						"callLabel": "",
						"smsAmount": -1,
						"callAmount": -1,
						"coverages": [
							"Afghanistan"
						],
						"networks": [
							"3G",
							"4G"
						],
						"signals": [
							{
								"code": "AF",
								"name": "Afghanistan",
								"networks": [
									"3G",
									"4G"
								],
								"carriers": [
									"Roshan"
								]
							}
						],
						"link": "https://www.getroamify.com/esim/afghanistan/?referrer=5Spg1dU0XRhHeUJGx6JFak4zccH2"
					},
					{
						"id": "92014f96-e231-4ea8-afbc-f5434dd78eee",
						"name": "3 GB - 15 Days",
						"price": 14.5,
						"validity": 15,
						"plan": "data-only",
						"dataAmount": 3072,
						"dataUnit": "MB",
						"data": "3 GB",
						"isUnlimited": false,
						"isActivated": true,
						"withKyc": false,
						"withTopUp": true,
						"withSMS": false,
						"withCall": false,
						"withHotspot": true,
						"smsUnit": "",
						"callUnit": "",
						"smsLabel": "",
						"callLabel": "",
						"smsAmount": -1,
						"callAmount": -1,
						"coverages": [
							"Afghanistan"
						],
						"networks": [
							"3G",
							"4G"
						],
						"signals": [
							{
								"code": "AF",
								"name": "Afghanistan",
								"networks": [
									"3G",
									"4G"
								],
								"carriers": [
									"Roshan"
								]
							}
						],
						"link": "https://www.getroamify.com/esim/afghanistan/?referrer=5Spg1dU0XRhHeUJGx6JFak4zccH2"
					},
					{
						"id": "b20dbf4f-415a-4545-9109-3ba9739f873b",
						"name": "3 GB - 30 Days",
						"price": 15.5,
						"validity": 30,
						"plan": "data-only",
						"dataAmount": 3072,
						"dataUnit": "MB",
						"data": "3 GB",
						"isUnlimited": false,
						"isActivated": true,
						"withKyc": false,
						"withTopUp": true,
						"withSMS": false,
						"withCall": false,
						"withHotspot": true,
						"smsUnit": "",
						"callUnit": "",
						"smsLabel": "",
						"callLabel": "",
						"smsAmount": -1,
						"callAmount": -1,
						"coverages": [
							"Afghanistan"
						],
						"networks": [
							"3G",
							"4G"
						],
						"signals": [
							{
								"code": "AF",
								"name": "Afghanistan",
								"networks": [
									"3G",
									"4G"
								],
								"carriers": [
									"Roshan"
								]
							}
						],
						"link": "https://www.getroamify.com/esim/afghanistan/?referrer=5Spg1dU0XRhHeUJGx6JFak4zccH2"
					}
                ]
            }
        ]
    }
}
```

--------------------------------

### Retrieve Roamify Account Balance

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

Example code demonstrating how to send a GET request to the Roamify eSIM API to retrieve the current account balance. Includes examples for both curl and JavaScript.

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

```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);
});
```

--------------------------------

### Create Roamify eSIM Top-up Order

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

Example code demonstrating how to send a POST request to the Roamify eSIM API to create a top-up order for an eSIM using its ICCID and a package ID. Includes examples for both curl and JavaScript.

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

```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);
});
```

--------------------------------

### Retrieve Roamify eSIM Packages via API

Source: https://docs.getroamify.com/affiliate/overview

Demonstrates how to make a GET request to the Roamify API to fetch a list of available eSIM packages. Examples are provided for both cURL and JavaScript using Axios.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/esimradar/packages' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Fetch Compatible eSIM Top-up Packages via Roamify API

Source: https://docs.getroamify.com/esims/esims

This snippet shows how to query the Roamify API for a list of top-up packages compatible with a specific eSIM. It details the API endpoint, necessary parameters, and offers cURL and JavaScript (Axios) examples for the GET request. The response provides a list of available top-up options with their specifications.

```APIDOC
GET /api/esim/topup/packages
  - Description: Retrieves a list of compatible top-up packages for a specific eSIM.
  - Parameters:
    - iccid (string, required): The ICCID of the eSIM.
  - Sample Response:
    {
      "status": "success",
      "data": [
        {
          "packageId": "esim-cambodia-7days-1gb-all",
          "package": "1 GB - 7 Days",
          "plan": "data-only",
          "activation": "first-use",
          "day": 7,
          "price": 5,
          "withHotspot": true,
          "withDataRoaming": true,
          "withDestinationInstall": false,
          "withUsageCheck": true,
          "apn": {
            "apnAutomatic": true,
            "apnName": "globaldata",
            "apnUsername": "",
            "apnPassword": ""
          },
          "data": {
            "isUnlimited": false,
            "dataAmount": 1024,
            "dataUnit": "MB"
          },
          "call": {
            "withCall": false,
            "callType": "all",
            "callAmount": -1,
            "callUnit": ""
          },
          "sms": {
            "withSMS": false,
            "smsType": "all",
            "smsAmount": -1,
            "smsUnit": ""
          },
          "notes": []
        }
      ]
    }
```

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

```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);
});
```

--------------------------------

### Roamify eSIM API: Get Packages Endpoint

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

Documentation for the `/api/esim/packages` GET endpoint, used to retrieve a list of available eSIM packages. This endpoint does not require any request body or query parameters, only authentication.

```APIDOC
GET /api/esim/packages
  - Description: Retrieves a list of available eSIM packages.
  - Authentication: Requires a Bearer Access Token.
  - Parameters: None.
```

--------------------------------

### Fetch Account Balance with JavaScript (Axios)

Source: https://docs.getroamify.com/esims/balance

JavaScript example using the Axios library to perform a GET request to the /api/balance endpoint, demonstrating how to include headers and handle both success and error responses.

```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);
});
```

--------------------------------

### Retrieve eSIM Packages with Affiliate Links via GET Request

Source: https://docs.getroamify.com/affiliate/affiliate-links

Demonstrates how to fetch a list of all available eSIM packages, each containing a unique referral link, from the Roamify eSIM API. This involves sending an authenticated GET request to the `/api/esim/{unique name}/packages` endpoint. The referral link includes a unique identifier for tracking sales.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/esimradar/packages' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Create eSIM Order via Roamify API

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

This snippet illustrates how to submit an eSIM order to the Roamify API using a POST request to the `/api/esim/order` endpoint. It includes examples for both curl and JavaScript, demonstrating how to pass the `items` array in the request body.

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

```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);
});
```

--------------------------------

### Retrieve eSIM Packages from Roamify API

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

This snippet demonstrates how to fetch a list of available eSIM packages from the Roamify API using a GET request to the `/api/esim/packages` endpoint. It requires an Authorization Bearer token for authentication.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/packages' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Fetch eSIM Supported Countries API Call Examples

Source: https://docs.getroamify.com/esims/countries

Provides practical examples for fetching a list of eSIM supported countries from the Roamify API. It includes a cURL command for direct terminal execution and a JavaScript snippet using Axios for integration into web applications, both demonstrating proper authentication.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/countries' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Fetch eSIM Orders with cURL

Source: https://docs.getroamify.com/esims/orders

Example cURL command to perform a GET request to the /api/esim/orders endpoint, demonstrating how to include authorization headers and query parameters like 'status' and 'limit'.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/orders?status=PENDING&limit=10' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

--------------------------------

### Roamify eSIM API: Get Usage Endpoint

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

Documentation for the `/api/esim/usage` GET endpoint, used to retrieve usage details for a specific eSIM. It details the required `iccid` query parameter.

```APIDOC
GET /api/esim/usage
  - Description: Retrieves the usage details for a specific eSIM.
  - Authentication: Requires a Bearer Access Token.
  - Query Parameters:
    - iccid: string (required)
      - Description: The ICCID of the eSIM for which to retrieve usage.
```

--------------------------------

### Example JSON Response for eSIM Packages API

Source: https://docs.getroamify.com/esims/packages

This JSON block provides a sample structure of the data returned by the `/api/esim/packages` endpoint. It details the `status`, `data` containing `packages`, and the comprehensive attributes for each eSIM package, including pricing, data limits, and network information.

```json
{
	"status": "success",
	"data": {
		"packages": [
			{
				"id": "afghanistan-esims",
				"countryName": "Afghanistan",
				"countryCode": "AF",
				"countrySlug": "afghanistan",
				"region": "Asia",
				"geography": "local",
				"minPrice": 5,
				"maxPrice": 5,
				"image": "https://imagedelivery.net/uUE6LNs_ci8SFBH4_n66dQ/countries/flags/afghanistan/public",
				"signals": [
					{
						"code": "AF",
						"name": "Afghanistan",
						"networks": [
							"3G",
							"4G"
						],
						"carriers": [
							"MTN"
						]
					}
				],
				"packages": [
					{
						"packageId": "esim-canada-15days-un2gb-all",
						"package": "Unlimited Data - 15 Days (2 GB / 128 KBPS)",
						"plan": "data-only",
						"activation": "first-use",
						"day": 15,
						"price": 1.32,
						"isUnlimited": true,
						"isAPNAutomatic": true,
						"apn": "drei.at",
						"dataAmount": 9007199254740991,
						"dataUnit": "MB",
						"callType": "all",
						"callAmount": -1,
						"callUnit": "",
						"smsType": "all",
						"smsAmount": -1,
						"smsUnit": "",
						"withSMS": false,
						"withCall": false,
						"withHotspot": true,
						"withDataRoaming": true,
						"withDestinationInstall": false,
						"withUsageCheck": true,
						"withThrottle": true,
						"throttle": {
							"throttleSpeed": 128,
							"throttleSpeedUnit": "kbps",
							"throttleThreshold": 2,
							"throttleThresholdUnit": "gb"
						},
						"notes": []
					}
				]
			}
        ]
    }
}
```

--------------------------------

### Fetch Account Balance with cURL

Source: https://docs.getroamify.com/esims/balance

Example cURL command to make a GET request to the /api/balance endpoint, including necessary authorization and content type headers to retrieve the account balance.

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

--------------------------------

### Fetch Basic eSIM Usage Details via Roamify API

Source: https://docs.getroamify.com/esims/esims

This snippet demonstrates how to retrieve the basic usage details of an eSIM using the Roamify API. It includes the API endpoint specification, required parameters, and code examples for both cURL and JavaScript (Axios) to perform the GET request. The response provides high-level data consumption information.

```APIDOC
GET /api/esim/usage
  - Description: Retrieves basic usage details for an eSIM.
  - Parameters:
    - iccid (string, required): The ICCID of the eSIM.
  - Sample Response:
    {
      "status": "success",
      "data": {
        "id": "xxxxxxx-xxxxxx-xxxxxx-xxxxxx",
        "iccid": "894000000000029365",
        "status": "INSTALLED",
        "startedAt": 1732442794,
        "expiredAt": 1732442794,
        "allowedData": 1024,
        "remainingData": 924,
        "allowedSms": 0,
        "remainingSms": 0,
        "allowedVoice": 0,
        "remainingVoice": 0
      }
    }
```

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

```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);
});
```

--------------------------------

### Sample Roamify API Response: List of eSIMs

Source: https://docs.getroamify.com/esims/esims

Provides an example of the JSON response received when successfully querying the /api/esims endpoint, showcasing an array containing one or more eSIM objects with their detailed properties.

```json
{
	"status": "success",
	"data": [
		{
			"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
			"iccid": "894000000000029365",
			"status": "READY",
			"activation": "first-use",
			"withTopUp": true,
			"withHotspot": true,
			"withDataRoaming": true,
			"withDestinationInstall": false,
		    "withUsageCheck": true,
			"esim": {
				"lpaCode": "LPA:1$lpa.roamify.com$TEST",
				"smdpAddress": "lpa.roamify.com",
				"activationCode": "TEST",
				"qrCodeUrl": "https://imagedelivery.net/uUE6LNs_ci8SFBH4_n66dQ/partners/b06036c5-eadc-4f88-aa31-8c207fec91ec/iccid/public",
				"pin": "",
				"puk": "",
				"number": "",
				"iosQuickInstall": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.roamify.com$TEST"
			},
			"apn": {
				"apnAutomatic": true,
				"apnName": "",
				"apnUsername": "",
				"apnPassword": ""
			},
			"data": {
				"isUnlimited": false
			},
			"call": {
				"withCall": false,
				"callType": "all"
			},
			"sms": {
				"withSMS": false,
				"smsType": "all"
			},
			"notes": [],
			"createdAt": 1731837539,
			"updatedAt": 1731838043,
			"expiredAt": 1732442794
		}
	]
}
```

--------------------------------

### Example eSIM Usage Event Webhook Payload

Source: https://docs.getroamify.com/webhooks/types/esim-usage

Illustrates a sample JSON payload for an eSIM usage event webhook, demonstrating the typical structure and data values for various fields including usage data and a list of usage records.

```JSON
{
  "event_category": "esim",
  "event_type": "usage",
  "timestamp": 1700000000,
  "iccid": "8991234567890123456",
  "esim_id": "c2a9cdae-430e-4251-bf65-a84df4562ed9",
  "reference_id": "ref_1234567890",
  "start": 1699996800,
  "end": 1700000400,
  "status": "ACTIVATED",
  "package_id": "esim-afghanistan-7days-1gb-all",
  "package_name": "1 GB - 7 Days",
  "data_units": "MB",
  "voice_units": "minutes",
  "sms_units": "sms",
  "usage_data": {
     "isUnlimited": false,
     "allowed_data": 1024,
     "remaining_data": 512,
     "allowed_sms": 100,
     "remaining_sms": 50,
     "allowed_voice": 500,
     "remaining_voice": 250
  },
    "usage_list": [
        {
          "date": "2023-11-01",
          "data_used": 100,
          "location": "Afghanistan"
        },
        {
          "date": "2023-11-02",
          "data_used": 200,
          "location": "Afghanistan"
        }
    ]
}
```

--------------------------------

### Roamify eSIM API: Top-up an eSIM Endpoint

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

Defines the API endpoint for topping up an eSIM, including the HTTP method, path, and required request body parameters (ICCID and package ID) with their types.

```APIDOC
POST /api/esim/order/topup
  - Description: Top-up an eSIM if the balance is low or data limit is reached.
  - Request Body Parameters:
    - iccid: string (required) - The ICCID of the eSIM to top-up.
    - packageId: string (required) - The ID of the eSIM package to top-up.
```

--------------------------------

### Fetch a List of Roamify Gift Cards with Optional Filtering

Source: https://docs.getroamify.com/gift-cards/get-gift-card

This snippet describes how to retrieve a collection of gift cards via a GET request to the `/api/gifts/gifts` endpoint. It supports optional filtering by `status` and provides a code example in cURL.

```APIDOC
GET /api/gifts/gifts
  - Description: Retrieve a list of gift cards.
  - Parameters:
    - status: string (optional)
      - Description: The status of the gift card.
      - Possible values: NEW, REDEEMED, EXPIRED, VOIDED, REFUNDED, UNKNOWN.
  - Authentication: Bearer Token (required)
```

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/gifts/gifts?status=NEW' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

--------------------------------

### Example eSIM Status Event Webhook Payload

Source: https://docs.getroamify.com/webhooks/types/esim-status

Illustrates a sample JSON payload for the eSIM Status Event webhook, showing typical values for each field when an eSIM's status changes to 'ACTIVATED'. This example helps in understanding the data format received by the webhook listener.

```json
{
  "event_category": "esim",
  "event_type": "status",
  "timestamp": 1700000000,
  "iccid": "8991234567890123456",
  "esim_id": "c2a9cdae-430e-4251-bf65-a84df4562ed9",
  "reference_id": "ref_1234567890",
  "start": 1699996800,
  "end": 1700000400,
  "status": "ACTIVATED"
}
```

--------------------------------

### Example Response for Get eSIM Orders

Source: https://docs.getroamify.com/esims/orders

A typical JSON structure returned by the /api/esim/orders endpoint, illustrating the 'status' and 'data' fields, including an array of 'orders' with detailed properties like 'id', 'referenceId', 'status', and 'items'.

```json
{
	"status": "success",
	"data": {
		"orders": [
			{
				"id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
                "referenceId": "ref-123456",
				"orderType": "api",
				"status": "COMPLETED",
				"total": 5,
				"currency": "USD",
				"createdAt": 1731837535,
				"updatedAt": 1731837539,
				"items": [
					{
						"esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
						"packageId": "esim-cambodia-7days-1gb-all",
						"package": "1 GB - 7 Days",
						"type": "esim",
						"price": 5,
						"currency": "USD",
						"createdAt": 1731837535,
						"updatedAt": 1731837539
					}
				]
			}
		]
	}
}
```

--------------------------------

### Generate eSIM Profile: JavaScript Axios Example

Source: https://docs.getroamify.com/esims/esims

Illustrates how to use the Axios library in JavaScript to send a POST request to the `/api/esim/apply` endpoint, generating an eSIM profile by providing an `esimId`.

```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);
});
```

--------------------------------

### Roamify eSIM API: Get Account Balance Endpoint

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

Defines the API endpoint for retrieving the remaining balance of funds, specifying the HTTP method, path, and confirming that no parameters are required.

```APIDOC
GET /api/balance
  - Description: Get the remaining balance of your funds.
  - Parameters: None
```

--------------------------------

### Affiliate Orders Event Webhook Payload Definition and Example

Source: https://docs.getroamify.com/webhooks/types/affiliate-orders

Defines the structure of the webhook payload for affiliate order events, including all fields, their types, and nested objects like order data and items. Provides a comprehensive example JSON payload for reference.

```APIDOC
Webhook Event Payload:

event_category: string
  - The category of event. For affiliate events, this will be `affiliate`.
event_type: string
  - The type of event. For affiliate order events, this will be `order`.
timestamp: number (unix timestamp)
  - The time when the event was triggered, in unix timestamp format (seconds since epoch).
partner_name: string
  - The name of the affiliate partner.
partner_id: string
  - The unique identifier of the affiliate account.
commission_rate: number (float)
  - The commission rate for the order, expressed as a percentage.
commission_amount: number (float)
  - The total commission amount earned from the order.
order_data: object
  - Object containing order information:
    order_id: string
      - The unique identifier of the order.
    order_total: number (float)
      - The total amount of the order.
    order_adjustment: number (float)
      - The adjusted total amount of the order after any redeemable credits or adjustments.
    order_subtotal: number (float)
      - The subtotal amount of the order before any discounts.
    order_discount: number (float)
      - The discount applied to the order, if any.
    order_currency: string (ISO 4217)
      - The currency of the order, in ISO 4217 format (e.g., USD, EUR).
    order_status: string
      - The status of the order. Possible values include:
        - `completed`: The order has been completed successfully.
        - `pending`: The order is pending processing.
        - `failed`: The order has failed.
        - `refunded`: The order has been refunded.
    order_items: array of objects
      - Array of items included in the order, each containing:
        item_id: string
          - The unique identifier of the item.
        item_name: string
          - The name of the item.
        item_quantity: number (integer)
          - The quantity of the item ordered.
        item_price: number (float)
          - The price of the item in USD.
```

```JSON
{
  "event_category": "affiliate",
  "event_type": "order",
  "timestamp": 1700000000,
  "partner_name": "ACME Affiliate",
  "partner_id": "6ImuFenqQbPjYaYyhWRIvkYdsF42",
  "commission_rate": 10.0,
  "commission_amount": 5.00,
  "order_data": {
    "order_id": "c2a9cdae-430e-4251-bf65-a84df4562ed9",
    "order_total": 49.99,
    "order_adjustment": 0.00,
    "order_subtotal": 49.99,
    "order_discount": 0.00,
    "order_currency": "USD",
    "order_status": "completed",
    "order_items": [
      {
        "item_id": "esim-afghanistan-7days-1gb-all",
        "item_name": "1 GB - 7 Days",
        "item_quantity": 1,
        "item_price": 49.99
      }
    ]
  }
}
```

--------------------------------

### Roamify eSIM API: Submit Order Endpoint

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

Documentation for the `/api/esim/order` POST endpoint, used to create new eSIM orders. It details the required request body parameters, including an `items` array with `packageId` and `quantity` for each eSIM.

```APIDOC
POST /api/esim/order
  - Description: Submits a new eSIM order.
  - Authentication: Requires a Bearer Access Token.
  - Request Body Parameters:
    - items: array (required)
      - Description: An array of eSIMs to order.
      - Each item in the array:
        - packageId: string (required)
          - Description: The ID of the eSIM package.
        - quantity: number (required)
          - Description: The quantity of the eSIMs to order.
```

--------------------------------

### Fetch a List of eSIMs from Roamify API

Source: https://docs.getroamify.com/esims/esims

Demonstrates how to programmatically retrieve a list of eSIMs from the Roamify API using both cURL and JavaScript (Axios). Both examples include necessary authorization and content type headers for the GET request to the /api/esims endpoint.

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esims' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Webhook Acknowledgment Response Example

Source: https://docs.getroamify.com/webhooks/types/esim-status

An example of the required 200 OK JSON response body for acknowledging a webhook receipt. This structure indicates successful processing and prevents webhook retries.

```JSON
{
  "code": 200,
  "status": "success"
}
```

--------------------------------

### Create eSIM Top-up Order (cURL & JavaScript)

Source: https://docs.getroamify.com/esims/orders

Provides examples for creating a top-up order for an existing eSIM using both cURL and Node.js with Axios. The request targets the `/api/esim/order/topup` endpoint and requires the eSIM's ICCID and a package ID.

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

```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);
});
```

--------------------------------

### Roamify eSIM API: Generate eSIM Endpoint

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

Documentation for the `/api/esim/apply` POST endpoint, used to generate an eSIM profile after an order has been submitted. It details the required `esimId` parameter in the request body.

```APIDOC
POST /api/esim/apply
  - Description: Generates an eSIM profile using a previously obtained eSIM ID.
  - Authentication: Requires a Bearer Access Token.
  - Request Body Parameters:
    - esimId: string (required)
      - Description: The ID of the eSIM to generate.
```

--------------------------------

### Fetch Detailed eSIM Usage History via Roamify API

Source: https://docs.getroamify.com/esims/esims

This snippet illustrates how to obtain comprehensive usage details and historical data for an eSIM from the Roamify API. It covers the API endpoint, required parameters, and provides cURL and JavaScript (Axios) examples for making the GET request. The response includes granular daily usage information.

```APIDOC
GET /api/esim/usage/details
  - Description: Retrieves detailed usage information and historical data for an eSIM.
  - Parameters:
    - iccid (string, required): The ICCID of the eSIM.
  - Notes:
    - If "withUsageCheck" property is false, usage check won't be supported. Refer to notes property for instructions.
  - Sample Response:
    {
      "status": "success",
      "data": {
        "id": "xxxxxxx-xxxxxx-xxxxxx-xxxxxx",
        "iccid": "894000000000029365",
        "status": "INSTALLED",
        "startedAt": 1732442794,
        "expiredAt": 1732442794,
        "allowedData": 1024,
        "remainingData": 924,
        "allowedSms": 0,
        "remainingSms": 0,
        "allowedVoice": 0,
        "remainingVoice": 0,
        "dataUsages": [
          {
            "date": "20250102",
            "usage": 10000,
            "location": "United Kingdom"
          },
          {
            "date": "20250103",
            "usage": 20000,
            "location": "United Kingdom"
          }
        ]
      }
    }
```

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

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

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

--------------------------------

### Check eSIM Usage via Roamify API

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

This snippet shows how to retrieve the usage details of an eSIM from the Roamify API by sending a GET request to the `/api/esim/usage` endpoint. It requires the `iccid` as a query parameter.

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

```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);
});
```

--------------------------------

### Generate eSIM Profile: cURL Example

Source: https://docs.getroamify.com/esims/esims

Demonstrates how to make a POST request to the `/api/esim/apply` endpoint using cURL to generate an eSIM profile, providing an `esimId` in the request body.

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

--------------------------------

### Webhook Acknowledgment Response Requirements and Example

Source: https://docs.getroamify.com/webhooks/types/affiliate-orders

Specifies the mandatory HTTP response required to acknowledge receipt of the webhook, including the status code and an example JSON body. Details retry behavior if no timely response is received.

```APIDOC
Webhook Acknowledgment Response:

HTTP Status Code: 200 OK
  - Required to acknowledge receipt of the webhook.
  - If no response within 5 seconds, webhook will be retried up to 3 times at increasing intervals.

Response Body Structure:
  code: number (integer)
    - Status code of the response (e.g., 200).
  status: string
    - Status message (e.g., "success").
```

```JSON
{
  "code": 200,
  "status": "success"
}
```

--------------------------------

### Roamify eSIM Order API Endpoints

Source: https://docs.getroamify.com/esims/orders

Comprehensive documentation for the Roamify eSIM Order API, detailing the endpoints for creating new orders, topping up existing eSIMs, and retrieving order information. Includes request methods, parameters, authentication requirements, and example request/response bodies for each operation.

```APIDOC
POST /api/esim/order
  Description: Creates a new eSIM order.
  Request Body Parameters:
    - items: array (required) - An array of package items to order.
      - packageId: string (required) - The unique identifier for the eSIM package.
      - quantity: number (required) - The number of units for the specified package.
  Authentication: Bearer Token in Authorization header.
  Example Request Body:
    {
      "items": [
        {
          "packageId": "Package ID",
          "quantity": 1
        }
      ]
    }
  Example Success Response (200 OK):
    {
      "status": "success",
      "data": {
        "id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
        "referenceId": "ref-123456",
        "orderType": "api",
        "status": "COMPLETED",
        "total": 5,
        "currency": "USD",
        "createdAt": 1731837535,
        "updatedAt": 1731837539,
        "items": [
          {
            "esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
            "packageId": "esim-cambodia-7days-1gb-all",
            "package": "1 GB - 7 Days",
            "type": "esim",
            "price": 5,
            "currency": "USD",
            "createdAt": 1731837535,
            "updatedAt": 1731837539
          }
        ]
      }
    }

POST /api/esim/order/topup
  Description: Creates a top-up order for an existing eSIM.
  Request Body Parameters:
    - iccid: string (required) - The ICCID of the eSIM to top-up.
    - packageId: string (required) - The ID of the eSIM package to apply for the top-up.
    - referenceId: string (optional) - A custom reference ID for the top-up order.
  Authentication: Bearer Token in Authorization header.
  Example Request Body:
    {
      "iccid": "ICCID",
      "packageId": "Package ID",
      "referenceId": "Optional Reference ID"
    }
  Example Success Response (200 OK):
    {
      "status": "success",
      "data": {
        "id": "0501aef3-7cf1-4b4c-a293-c03a6bd7a8ab",
        "referenceId": "ref-123456",
        "orderType": "api",
        "status": "COMPLETED",
        "total": 5,
        "currency": "USD",
        "createdAt": 1731838277,
        "updatedAt": 1731838280,
        "items": [
          {
            "esimId": "22dcdb84-968b-415c-bb70-79e2f3ffc296",
            "packageId": "esim-cambodia-7days-1gb-all",
            "package": "1 GB - 7 Days",
            "type": "esim",
            "price": 5,
            "currency": "USD",
            "createdAt": 1731838277,
            "updatedAt": 1731838280
          }
        ]
      }
    }

GET /api/esim/order
  Description: Retrieves details of a specific eSIM order.
  Query Parameters (at least one required):
    - orderId: string (optional) - The unique ID of the eSIM order.
    - referenceId: string (optional) - The custom reference ID of the eSIM order.
  Authentication: Bearer Token in Authorization header.
  Example Request URL:
    https://api-dev.getroamify.com/api/esim/order?orderId=Order ID
  Example Success Response (200 OK):
    {
      "status": "success",
      "data": {
        "id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
        "referenceId": "ref-123456",
        "orderType": "api",
        "status": "COMPLETED",
        "total": 5,
        "currency": "USD",
        "createdAt": 1731837535,
        "updatedAt": 1731837539,
        "items": [
          {
            "esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
            "packageId": "esim-cambodia-7days-1gb-all",
            "package": "1 GB - 7 Days",
            "type": "esim",
            "price": 5,
            "currency": "USD",
            "createdAt": 1731837535,
            "updatedAt": 1731837539
          }
        ]
      }
    }
```

--------------------------------

### Roamify eSIM API: Get Compatible Devices Endpoint

Source: https://docs.getroamify.com/esims/compatible-devices

Documents the `/api/compatible-devices` endpoint for retrieving a list of devices compatible with Roamify eSIMs. This GET request requires no parameters and returns a JSON object containing a 'data' array of device objects.

```APIDOC
GET /api/compatible-devices
  - Description: Retrieves a list of devices compatible with Roamify eSIMs.
  - Parameters: None required.
  - Returns: JSON object with 'status' and 'data' fields.
    {
      "status": "success",
      "data": [
        {
          "model": "Samsung Galaxy Note 20 / Note 20 Plus / Note 20 Ultra",
          "deviceType": "smartphone",
          "os": "android",
          "brand": "Samsung",
          "name": "Samsung Galaxy Note 20 series"
        },
        {
          "model": "Rakuten BIG / Rakuten BIG-S",
          "deviceType": "smartphone",
          "os": "android",
          "brand": "Rakuten",
          "name": "Rakuten BIG series"
        }
      ]
    }
```

--------------------------------

### Create Gift Card using cURL

Source: https://docs.getroamify.com/gift-cards/create-gift-card

Example cURL command to send a POST request to the Roamify API for creating a gift card. This demonstrates how to set authorization, content type, and provide the necessary JSON request body with sample values.

```curl
curl --request POST \
--url 'https://api-dev.getroamify.com/api/gifts/gift' \
--header 'Authorization: Bearer AssessToken' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": "your-order-id",
    "amount": 100,
    "currency": "USD",
    "senderEmail": "test@mail.com",
    "sender": ""
}'
```

--------------------------------

### Generate eSIM Profile via Roamify API

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

This snippet demonstrates how to generate an eSIM profile using the Roamify API by sending a POST request to the `/api/esim/apply` endpoint. It requires an `esimId` obtained from a previous order submission.

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

```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);
});
```

--------------------------------

### Roamify eSIM API: Get Orders Endpoint Reference

Source: https://docs.getroamify.com/esims/orders

Defines the GET /api/esim/orders endpoint, detailing its purpose, optional query parameters (status, limit, referenceId), their types, valid values, and the expected return structure.

```APIDOC
GET /api/esim/orders
  - Description: Retrieves a list of eSIM orders.
  - Optional Parameters:
    - status (string): Filter orders by their current status.
      - Valid Values: PENDING, COMPLETED, ARCHIVED, CANCELLED, REFUNDED, REQUIRE_ACTION
    - limit (number): Specifies the maximum number of orders to return. Default is 50.
    - referenceId (string): Filters orders by a specific external reference identifier.
  - Returns: A JSON object containing an array of eSIM order details.
```

--------------------------------

### Fetch eSIM Package History

Source: https://docs.getroamify.com/esims/esims

Demonstrates how to retrieve a history of eSIM packages applied to a specific eSIM using the Roamify eSIM API. This involves a GET request to the `/api/esim/history` endpoint, requiring an ICCID and an Authorization header. The response provides details about past package activations.

```APIDOC
GET /api/esim/history
  - Description: Retrieves a history of eSIM packages applied to an eSIM.
  - Parameters:
    - iccid: string (required) - The ICCID of the eSIM.
  - Headers:
    - Authorization: Bearer {Access Token}
    - Content-Type: application/json
  - Returns: JSON object with status and an array of package history data.
  - Example Response:
    {
        "status": "success",
        "data": [
            {
                "esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
                "packageId": "esim-cambodia-7days-1gb-all",
                "package": "1 GB - 7 Days",
                "type": "esim",
                "price": 5,
                "currency": "USD",
                "createdAt": 1731837535,
                "updatedAt": 1731837539
            }
        ]
    }
```

```curl
curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/history?iccid=ICCID' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'
```

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

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

--------------------------------

### Create eSIM Order using cURL

Source: https://docs.getroamify.com/esims/orders

Example cURL command to create a new eSIM order. This command sends a POST request to the `/api/esim/order` endpoint, including the necessary `Authorization` header with a Bearer token and a JSON request body specifying the `packageId`, `quantity`, and an optional `referenceId`.

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