eSIMs · After the order

Get eSIM installation instructions

Get step-by-step installation instructions for one eSIM, per operating system, in the language of the request.

GET/api/v1/esims/instructions/{iccid}

Requires an API key with Read permission; a Read+Write key works too.

The steps are generic text of the supplier: they say the activation details are "available on the app". Show the QR code and the activation data of the order next to the steps in your own product. The response also contains the activation data of the eSIM, so show it only to the traveler who owns it.

curl https://api.fx-port.com/api/v1/esims/instructions/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"

Response200

{
  "environment": "sandbox",
  "success": true,
  "data": {
    "data": {
      "instructions": {
        "language": "EN",
        "ios": [
          {
            "model": null,
            "version": "15.0,14.0,13.0,12.0",
            "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
            "installation_via_qr_code": {
              "steps": {
                "1": "Go to “Settings”, tap “Cellular/Mobile Data”, then tap “Add Cellular/Data Plan” on your device.",
                "2": "Scan the QR code available on the  app, then tap “Add Cellular/Data Plan”.",
                "3": "Choose a label for your new eSIM plan."
              },
              "qr_code_data": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
              "qr_code_url": "https://sandbox.airalo.com/qr?expires=1879860202&id=473564&signature=..."
            },
            "installation_manual": {
              "steps": {
                "1": "Go to “Settings”, tap “Cellular/Mobile Data”, then tap “Add Cellular/Data Plan” on your device.",
                "2": "Tap “Enter Details Manually” and enter the SM-DP+ Address and Activation Code available on the  app by copying them, tap “Next”, then tap “Add Cellular/Data Plan”."
              },
              "smdp_address_and_activation_code": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
              "smdp_address": "lpa.airalo.com",
              "activation_code": "DUMMY-2610301358-iKFxr-44741"
            },
            "network_setup": {
              "steps": {
                "1": "Go to “Cellular/Mobile Data”, then select the recently downloaded eSIM on your device. Enable the “Turn On This Line” toggle, then select your new eSIM plan for cellular/mobile data.",
                "2": "Tap “Cellular/Mobile Data Network”, then enter the APN available on the  app in all APN fields by copying it."
              },
              "apn_type": "automatic",
              "apn_value": "N/A",
              "is_roaming": true
            }
          }
        ],
        "android": [
          {
            "model": null,
            "version": null,
            "direct_android_installation_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
            "installation_via_qr_code": {
              "steps": {
                "1": "Go to “Settings”, tap “Connections”, then tap “SIM card manager” on your device.",
                "2": "Tap “Add mobile plan”, then tap “Scan carrier QR code”.",
                "3": "Scan the QR code available on the  app, then tap “Confirm”."
              },
              "qr_code_data": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
              "qr_code_url": "https://sandbox.airalo.com/qr?expires=1879860202&id=473564&signature=..."
            },
            "installation_manual": {
              "steps": {
                "1": "Go to “Settings”, tap “Connections”, then tap “SIM card manager” on your device.",
                "2": "Tap “Add mobile plan”, then tap “Scan carrier QR code”.",
                "3": "Tap “Enter activation code”."
              },
              "smdp_address_and_activation_code": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741"
            },
            "network_setup": {
              "steps": {
                "1": "Go to “SIM card manager”, then turn on your eSIM by enabling the toggle, then tap “OK” on your device.",
                "2": "Select your eSIM for mobile data."
              },
              "apn_type": "automatic",
              "apn_value": "N/A",
              "is_roaming": true
            }
          }
        ]
      }
    },
    "meta": {
      "message": "success"
    }
  }
}

Request

Path parameters

iccidstringrequired

The eSIM to explain. It must be an eSIM that your agency ordered.

Query parameters

localestring

Language of the text fields. Without it the Accept-Language header is used, then en. Any spelling of a locale is read and only its language counts: fr, fr-CA, zh-Hans, pt_BR, fr_FR.UTF-8, or a whole Accept-Language value such as fr-FR,fr;q=0.9 (the first language is used). Supported: en, fr, ar, de, es, it, ja, ko, pl, pt, ro, ru, sq, tr, vi, zh. Another well-formed language is answered in English and the response carries a coerced_value warning.

At most 80 characters.

Response

200The instructions.

successboolean

true when the instructions were returned.

dataobject

Wrapper object: the steps are in data.data.instructions.

ShowHide 2 attributes

dataobject

Wrapper object.

ShowHide 1 attribute

instructionsobject

The steps per operating system.

ShowHide 3 attributes

languagestring

Language of the steps, upper case, for example EN.

iosarray of object

Steps for iPhones.

ShowHide 7 attributes

modelstringnullable

A device model the steps are written for, or null for every model.

versionstringnullable

Operating system versions the steps apply to, comma separated, or null for every version.

direct_apple_installation_urlstring

Link that starts the installation on an iPhone. iOS entries only.

direct_android_installation_urlstring

Link that starts the installation on an Android phone. Android entries only.

installation_via_qr_codeobject

Steps to install the eSIM by scanning its QR code.

ShowHide 3 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

qr_code_datastring

The activation string the QR code encodes: LPA:1$<host>$<activation code>.

qr_code_urlstring

Link to the QR code image.

installation_manualobject

Steps to install the eSIM by entering its activation data by hand.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

smdp_address_and_activation_codestring

The SM-DP+ address and the activation code in one string: LPA:1$<host>$<activation code>.

smdp_addressstring

The SM-DP+ address on its own. iOS entries only.

activation_codestring

The activation code on its own. iOS entries only.

network_setupobject

Steps to select the network and turn on data roaming, with the APN to enter.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

apn_typestring

automatic or manual.

apn_valuestring

The APN to enter, or N/A.

is_roamingboolean

Whether data roaming has to be turned on.

androidarray of object

Steps for Android phones.

ShowHide 7 attributes

modelstringnullable

A device model the steps are written for, or null for every model.

versionstringnullable

Operating system versions the steps apply to, comma separated, or null for every version.

direct_apple_installation_urlstring

Link that starts the installation on an iPhone. iOS entries only.

direct_android_installation_urlstring

Link that starts the installation on an Android phone. Android entries only.

installation_via_qr_codeobject

Steps to install the eSIM by scanning its QR code.

ShowHide 3 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

qr_code_datastring

The activation string the QR code encodes: LPA:1$<host>$<activation code>.

qr_code_urlstring

Link to the QR code image.

installation_manualobject

Steps to install the eSIM by entering its activation data by hand.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

smdp_address_and_activation_codestring

The SM-DP+ address and the activation code in one string: LPA:1$<host>$<activation code>.

smdp_addressstring

The SM-DP+ address on its own. iOS entries only.

activation_codestring

The activation code on its own. iOS entries only.

network_setupobject

Steps to select the network and turn on data roaming, with the APN to enter.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

apn_typestring

automatic or manual.

apn_valuestring

The APN to enter, or N/A.

is_roamingboolean

Whether data roaming has to be turned on.

metaobject

The supplier's status line.

ShowHide 1 attribute

messagestring

success when the supplier answered.

Errors

Status	Code	Example message
400	`invalid_locale`	locale must be a language code such as en, fr or ar (received '12').
404	`iccid_not_found`	No eSIM with this ICCID was found for your account.
503	`service_unavailable`	Airalo token unavailable

The shape of the error body depends on the endpoint. See Errors for every shape and code.

{ "environment": "sandbox", "success": true, "data": { "data": { "instructions": { "language": "EN", "ios": [ { "model": null, "version": "15.0,14.0,13.0,12.0", "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "installation_via_qr_code": { "steps": { "1": "Go to “Settings”, tap “Cellular/Mobile Data”, then tap “Add Cellular/Data Plan” on your device.", "2": "Scan the QR code available on the app, then tap “Add Cellular/Data Plan”.", "3": "Choose a label for your new eSIM plan." }, "qr_code_data": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "qr_code_url": "https://sandbox.airalo.com/qr?expires=1879860202&id=473564&signature=..." }, "installation_manual": { "steps": { "1": "Go to “Settings”, tap “Cellular/Mobile Data”, then tap “Add Cellular/Data Plan” on your device.", "2": "Tap “Enter Details Manually” and enter the SM-DP+ Address and Activation Code available on the app by copying them, tap “Next”, then tap “Add Cellular/Data Plan”." }, "smdp_address_and_activation_code": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "smdp_address": "lpa.airalo.com", "activation_code": "DUMMY-2610301358-iKFxr-44741" }, "network_setup": { "steps": { "1": "Go to “Cellular/Mobile Data”, then select the recently downloaded eSIM on your device. Enable the “Turn On This Line” toggle, then select your new eSIM plan for cellular/mobile data.", "2": "Tap “Cellular/Mobile Data Network”, then enter the APN available on the app in all APN fields by copying it." }, "apn_type": "automatic", "apn_value": "N/A", "is_roaming": true } } ], "android": [ { "model": null, "version": null, "direct_android_installation_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "installation_via_qr_code": { "steps": { "1": "Go to “Settings”, tap “Connections”, then tap “SIM card manager” on your device.", "2": "Tap “Add mobile plan”, then tap “Scan carrier QR code”.", "3": "Scan the QR code available on the app, then tap “Confirm”." }, "qr_code_data": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "qr_code_url": "https://sandbox.airalo.com/qr?expires=1879860202&id=473564&signature=..." }, "installation_manual": { "steps": { "1": "Go to “Settings”, tap “Connections”, then tap “SIM card manager” on your device.", "2": "Tap “Add mobile plan”, then tap “Scan carrier QR code”.", "3": "Tap “Enter activation code”." }, "smdp_address_and_activation_code": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741" }, "network_setup": { "steps": { "1": "Go to “SIM card manager”, then turn on your eSIM by enabling the toggle, then tap “OK” on your device.", "2": "Select your eSIM for mobile data." }, "apn_type": "automatic", "apn_value": "N/A", "is_roaming": true } } ] } }, "meta": { "message": "success" } } }

Request

Path parameters

iccidstringrequired

The eSIM to explain. It must be an eSIM that your agency ordered.

Query parameters

localestring

At most 80 characters.

Response

200The instructions.

successboolean

true when the instructions were returned.

dataobject

Wrapper object: the steps are in data.data.instructions.

ShowHide 2 attributes

dataobject

Wrapper object.

ShowHide 1 attribute

instructionsobject

The steps per operating system.

ShowHide 3 attributes

languagestring

Language of the steps, upper case, for example EN.

iosarray of object

Steps for iPhones.

ShowHide 7 attributes

modelstringnullable

A device model the steps are written for, or null for every model.

versionstringnullable

Operating system versions the steps apply to, comma separated, or null for every version.

direct_apple_installation_urlstring

Link that starts the installation on an iPhone. iOS entries only.

direct_android_installation_urlstring

Link that starts the installation on an Android phone. Android entries only.

installation_via_qr_codeobject

Steps to install the eSIM by scanning its QR code.

ShowHide 3 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

qr_code_datastring

The activation string the QR code encodes: LPA:1$<host>$<activation code>.

qr_code_urlstring

Link to the QR code image.

installation_manualobject

Steps to install the eSIM by entering its activation data by hand.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

smdp_address_and_activation_codestring

The SM-DP+ address and the activation code in one string: LPA:1$<host>$<activation code>.

smdp_addressstring

The SM-DP+ address on its own. iOS entries only.

activation_codestring

The activation code on its own. iOS entries only.

network_setupobject

Steps to select the network and turn on data roaming, with the APN to enter.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

apn_typestring

automatic or manual.

apn_valuestring

The APN to enter, or N/A.

is_roamingboolean

Whether data roaming has to be turned on.

androidarray of object

Steps for Android phones.

ShowHide 7 attributes

modelstringnullable

A device model the steps are written for, or null for every model.

versionstringnullable

Operating system versions the steps apply to, comma separated, or null for every version.

direct_apple_installation_urlstring

Link that starts the installation on an iPhone. iOS entries only.

direct_android_installation_urlstring

Link that starts the installation on an Android phone. Android entries only.

installation_via_qr_codeobject

Steps to install the eSIM by scanning its QR code.

ShowHide 3 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

qr_code_datastring

The activation string the QR code encodes: LPA:1$<host>$<activation code>.

qr_code_urlstring

Link to the QR code image.

installation_manualobject

Steps to install the eSIM by entering its activation data by hand.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

smdp_address_and_activation_codestring

The SM-DP+ address and the activation code in one string: LPA:1$<host>$<activation code>.

smdp_addressstring

The SM-DP+ address on its own. iOS entries only.

activation_codestring

The activation code on its own. iOS entries only.

network_setupobject

Steps to select the network and turn on data roaming, with the APN to enter.

ShowHide 4 attributes

stepsobject

The steps as text, keyed by their number: "1", "2", ...

apn_typestring

automatic or manual.

apn_valuestring

The APN to enter, or N/A.

is_roamingboolean

Whether data roaming has to be turned on.

metaobject

The supplier's status line.

ShowHide 1 attribute

messagestring

success when the supplier answered.

Errors

Status	Code	Example message
400	`invalid_locale`	locale must be a language code such as en, fr or ar (received '12').
404	`iccid_not_found`	No eSIM with this ICCID was found for your account.
503	`service_unavailable`	Airalo token unavailable

The shape of the error body depends on the endpoint. See Errors for every shape and code.

Request

Path parameters

Query parameters

Response

Errors

Related guides

Request

Path parameters

Query parameters

Response

Errors

Related guides