Skip to Content
🚀 Trusted by travel businesses worldwide - Roamify eSIM API
eSIMs ModuleeSIMs

eSIM API - Manage eSIMs

Table of Contents

Generate eSIM Profile

After you placed an order for eSIMs, you will get a dedicated ID called esimId for each eSIM. You can use this ID to generate a eSIM profile and ready to be used by your customers.

To apply an eSIM profile, you need to send a POST request to the /api/esim/apply endpoint.

⚠️

Due to server load, the eSIM profile generation can take up to 90 seconds. Please make sure the timeout of your request is set to at least 90 seconds.

🚫

If your request times out or failed with a error message stating: “eSIM is still pending processing”, please send a follow up request to /esim?esimId=YOUR_ESIM_ID to retrieve the eSIM.

The request body should contain the following parameters:

  • esimId: The ID of the eSIM. This is a required field of type string.

Usage - generate eSIM profile

Here is an example of how you can apply an eSIM profile using Roamify eSIM API.

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"
}'

Sample Response

{
	"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": 1731837987,
		"expiredAt": 1763373985
	}
}

Get eSIM Usage

To get the usage details of an eSIM, you need to send a GET request to the /api/esim/usage endpoint.

⚠️

Watch out property “withUsageCheck”, if it is set to false, usage check won’t be supported, find instructions in the notes property

The parameters required for this endpoint are:

  • iccid: The ICCID of the eSIM. This is a required field of type string.

Usage - fetch eSIM usage

Here is an example of how you can get the usage details of an eSIM using Roamify eSIM API.

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

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
	}
}

Get eSIM Usage Details

To get the usage details of an eSIM, you need to send a GET request to the /api/esim/usage/details endpoint.

⚠️

Watch out property “withUsageCheck”, if it is set to false, usage check won’t be supported, find instructions in the notes property

The parameters required for this endpoint are:

  • iccid: The ICCID of the eSIM. This is a required field of type string.

Usage - fetch eSIM usage

Here is an example of how you can get the usage details of an eSIM using Roamify eSIM API.

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'

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"
          }
        ]
	}
}

Get eSIM Compatible Top-ups

To get a list of compatible top-ups for an eSIM, you need to send a GET request to the /api/esim/topup/packages endpoint.

The parameters required for this endpoint are:

  • iccid: The ICCID of the eSIM. This is a required 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 --request GET \
--url 'https://api-dev.getroamify.com/api/esim/topup/packages?iccid=ICCID' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'

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": []
		}
    ]
}

Get eSIM Packages History

To get a history of eSIM packages applied to a eSIM, you need to send a GET request to the /api/esim/history endpoint.

The parameters required for this endpoint are:

  • iccid: The ICCID of the eSIM. This is a required field of type string.

Usage - fetch eSIM packages history

Here is an example of how you can get a history of eSIM packages applied to an eSIM using Roamify eSIM API.

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

Sample 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
		}
	]
}

Get eSIM By ICCID

To get an eSIM, you need to send a GET request to the /api/esim endpoint.

The request body should contain the following parameters:

  • iccid: The ICCID of the eSIM. This is a required field of type string.

Usage - fetch an eSIM

Here is an example of how you can get an eSIM using Roamify eSIM API.

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

Sample Response

{
	"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
	}
}

Get eSIM By eSIMID

Sometimes the generate eSIM profile request may fail due to server load. In such cases, you can use the eSIM ID to retrieve the eSIM details immediately after the previous request.

The request body should contain the following parameters:

  • esimId: The ID of the eSIM. This is a required field of type string.

Usage - fetch an eSIM by eSIM ID

Here is an example of how you can get an eSIM using Roamify eSIM API.

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim?esimId=YOUR eSIMID' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'

Sample Response

{
	"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
	}
}

Get eSIMs List

To get a list of eSIMs, you need to send a GET request to the /api/esims endpoint.

There are no required parameters for this endpoint, but you can provide the following optional parameters:

  • status: The status of the eSIM orders. This is an optional field of type string. It can be any of the following values:

    • NEW: New eSIM, not yet processed
    • READY: eSIM is ready to be downloaded
    • INSTALLED: eSIM has been installed
    • REVOKED: eSIM has been revoked
    • EXPIRED: eSIM has expired
    • UNKNOWN: Unknown status

  • limit: The number of eSIM orders to return. This is an optional field of type number. The default value is 50.

Usage - fetch a list of eSIMs

Here is an example of how you can get a list of eSIMs using Roamify eSIM API.

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

Sample Response

{
	"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
		}
	]
}
Last updated on
OrdersCompatible Devices