Connectivity

Advanced eSIM

The eUICC API lets you manage eSIM profiles on SGP.32 IoT eSIM devices programmatically. You can retrieve eUICC information, schedule profile operations, and monitor their status - all without accessing the emnify Portal.

Prerequisites

All eUICC API calls require a valid authentication token in the Authorization header. For instructions on obtaining a token, see Application tokens.

List your eUICCs

Retrieve all eUICCs registered to your organization. Use the q query parameter to filter by EID or other fields.

Endpoint: GET /api/v1/euicc

GET
/api/v1/euicc
1curl -G https://cdn.emnify.net/api/v1/euicc \
2     -H "Authorization: Bearer <token>" \
3     -d page=1 \
4     -d per_page=25
Try it
Response
1[
2  {
3    "id": 123456,
4    "eid": "89634247065724874780755570224832",
5    "created": "2025-08-26T09:31:51.000Z",
6    "profile": [
7      {
8        "iccid_with_luhn": "89883030000123456789",
9        "status": {
10          "id": 1,
11          "description": "Available"
12        },
13        "customer_org": {
14          "id": 44,
15          "name": "emnify Test"
16        },
17        "name": "emnify IoT eSIM profile",
18        "operator": {
19          "id": 851,
20          "name": "emnify"
21        },
22        "preloaded": true,
23        "fallback_allowed": true,
24        "fallback_attribute": true,
25        "profile_type": {
26          "id": 5,
27          "description": "IoT eUICC Profile"
28        },
29        "endpoint": {
30          "id": 789123,
31          "name": "My device"
32        }
33      }
34    ],
35    "issuer_org": {
36      "id": 2,
37      "name": "emnify GmbH"
38    },
39    "customer_org": {
40      "id": 44,
41      "name": "emnify Test"
42    },
43    "supported_profile_type": {
44      "id": 5,
45      "description": "IoT eUICC Profile"
46    },
47    "status": {
48      "id": 1,
49      "description": "Active"
50    },
51    "last_audited": "2025-09-25T11:56:15.000Z",
52    "last_polled": "2025-09-25T11:56:15.000Z",
53    "last_synced": "2025-09-25T11:56:15.000Z",
54    "eim": {
55      "id": 1,
56      "description": "TBD"
57    }
58  }
59]

To filter by EID, use the q query parameter:

GET
/api/v1/euicc
1curl -G https://cdn.emnify.net/api/v1/euicc \
2     -H "Authorization: Bearer <token>" \
3     --data-urlencode q=eid:89634247065724874780755570225034
Try it
Response
1[
2  {
3    "id": 123789,
4    "eid": "89634247065724874780755570225034",
5    "created": "2025-08-26T09:31:51.000Z",
6    "profile": []
7  }
8]

Get a specific eUICC

Retrieve details for a single eUICC by its internal ID.

Endpoint: GET /api/v1/euicc/{euicc_id}

GET
/api/v1/euicc/:euicc_id
1curl https://cdn.emnify.net/api/v1/euicc/123456 \
2     -H "Authorization: Bearer <token>"
Try it
Response
1{
2  "id": 123457,
3  "eid": "89634247065724874780755570224933",
4  "created": "2025-08-26T09:31:51.000Z",
5  "profile": []
6}

Profile statuses

Each profile on an eUICC has a status field that reflects its current state in the lifecycle.

IDStatusDescription
1AvailableInitial state for profiles on the emnify SM-DP+. Profile is not linked to any end-user and can be picked at random for assignment.
2AllocatedProfile has been reserved but not yet associated to an eUICC (EID).
3LinkedProfile has been reserved for use and an EID has been provided. Transient - moves to Released.
4ConfirmedProfile has been confirmed. Transient - moves to Released.
5ReleasedProfile is ready to download, either through a QR code or through MDM using a pre-linked EID and default SM-DP+.
6DownloadedProfile has been downloaded from the server; final notification from the eUICC is still awaited. Transient - moves to Installed or Enabled.
7InstalledProfile is installed on the eUICC but not active.
8EnabledProfile is installed on the eUICC and currently active.
9DeletedProfile was installed on the eUICC and has since been deleted.
10UnknownProfile state is currently unknown.

Two additional profile fields control fallback behavior:

  • fallback_allowed - Indicates whether the profile type supports being designated as a fallback.
  • fallback_attribute - Indicates whether this specific profile is currently set as the fallback. When the active profile loses network connectivity, the device automatically switches to the fallback profile.

Schedule profile operations

Use POST /api/v1/euicc/{euicc_id}/operation to schedule profile operations on an eUICC. Each request body is an array, allowing you to schedule multiple operations at once.

Operations are executed asynchronously - the API returns immediately with a Scheduled status and a link header that points to the created operations. Use List operations or Get operation details to track progress.

This endpoint returns HTTP 404 for non-IoT eUICCs.

Operation action IDs

IDAction
1Audit eUICC
2Download profile
3Enable profile
4Set fallback attribute
5Delete profile

Validity period

The validity_period parameter defines how long (in seconds) the operation remains pending before it expires. The maximum value is 86400 seconds (24 hours) which is also the default value if not specified.

If the device is unreachable and the validity period elapses before the operation is executed, the operation transitions to Expired.

Contradicting operations

The API does not validate new operations against any already-scheduled operations for the same eUICC. If a new operation conflicts with a pending one - for example, scheduling two concurrent “Enable profile” requests targeting different profiles - only the first scheduled operation will be applied. Subsequent contradicting operations will not be executed.

Check for pending scheduled operations before scheduling a new one to avoid unintended conflicts.

Audit an eUICC

Synchronizes the eUICC state by fetching the latest profile and status information directly from the device. Run an audit when eUICC data appears out of sync with what the device reports.

POST
/api/v1/euicc/:euicc_id/operation
1curl -X POST https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '[
5  {
6    "action": {
7      "id": 1
8    },
9    "validity_period": 600
10  }
11]'
Try it
Response
1[
2  {
3    "id": "11111111-2222-3333-4444-555555555555",
4    "action": {
5      "id": 1,
6      "description": "Audit eUICC"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:05:00.000Z",
13    "last_updated_at": "2025-09-25T12:05:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    }
18  }
19]

Download a profile

Downloads a new profile to the eUICC using an activation code. The profile is fetched from the SM-DP+ server and installed on the device over-the-air.

ParameterTypeRequiredDescription
activation_codestringYesActivation code in 1$<SMDP_ADDRESS>$<MATCHING_ID> format (for example, 1$SMDP.EXAMPLE.COM$04386-AGYFT-A74Y8-3F815). Provided by emnify or a third-party SM-DP+ operator.
enablebooleanNoIf true, the profile is activated immediately after download. Defaults to false.
rollbackbooleanNoIf true, the device automatically reverts to the previously active profile if the newly enabled profile fails to connect to a network. Strongly recommended when enable: true.
validity_periodintegerNoHow long (in seconds) the operation remains pending before it expires. Range: 1-86400. Defaults to 86400 (24 hours).

Set both enable: true and rollback: true when you want the profile to go live immediately - rollback ensures the device can recover automatically if the new profile fails to attach to a network.

POST
/api/v1/euicc/:euicc_id/operation
1curl -X POST https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '[
5  {
6    "action": {
7      "id": 2
8    },
9    "validity_period": 600,
10    "activation_code": "1$SMDP.GSMA.COM$04386-AGYFT-A74Y8-3F815",
11    "enable": true,
12    "rollback": true
13  }
14]'
Try it
Response
1[
2  {
3    "id": "11111112-2222-3333-4444-555555555555",
4    "action": {
5      "id": 2,
6      "description": "Download profile"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:05:00.000Z",
13    "last_updated_at": "2025-09-25T12:05:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    }
18  }
19]

Enable a profile

Switches the active profile on the eUICC to the specified profile by ICCID.

Enabling a profile automatically deactivates the currently active profile. The previously active profile transitions to Installed (Inactive) status and remains installed on the eUICC.

Rollback recommended: Set rollback: true to automatically revert to the previously active profile if the newly enabled profile fails to connect to a network after activation. Without rollback, a failed profile switch may leave the device offline with no automatic recovery.

POST
/api/v1/euicc/:euicc_id/operation
1curl -X POST https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '[
5  {
6    "action": {
7      "id": 3
8    },
9    "validity_period": 600,
10    "iccid_with_luhn": "89883030000133194051",
11    "rollback": true
12  }
13]'
Try it
Response
1[
2  {
3    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
4    "action": {
5      "id": 3,
6      "description": "Enable profile"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:05:00.000Z",
13    "last_updated_at": "2025-09-25T12:05:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    },
18    "iccid_with_luhn": "89883030000133194051"
19  }
20]

Set a fallback profile

Designates a profile as the fallback - the profile the device automatically switches to if the active profile loses connectivity.

Only a Disabled (inactive) profile can be set as the fallback. There can only be one fallback profile per eUICC at a time - designating a new fallback replaces the previous one.

POST
/api/v1/euicc/:euicc_id/operation
1curl -X POST https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '[
5  {
6    "action": {
7      "id": 4
8    },
9    "validity_period": 600,
10    "iccid_with_luhn": "89883030000133194051"
11  }
12]'
Try it
Response
1[
2  {
3    "id": "aaaaaaab-bbbb-cccc-dddd-eeeeeeeeeeee",
4    "action": {
5      "id": 4,
6      "description": "Set fallback attribute"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:05:00.000Z",
13    "last_updated_at": "2025-09-25T12:05:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    },
18    "iccid_with_luhn": "89883030000133194051"
19  }
20]

Delete a profile

Removes a profile from the eUICC over-the-air.

You cannot delete the currently active profile. Enable a different profile first. Profile deletion is irreversible.

POST
/api/v1/euicc/:euicc_id/operation
1curl -X POST https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '[
5  {
6    "action": {
7      "id": 5
8    },
9    "validity_period": 600,
10    "iccid_with_luhn": "89883030000133194051"
11  }
12]'
Try it
Response
1[
2  {
3    "id": "aaaaaaac-bbbb-cccc-dddd-eeeeeeeeeeee",
4    "action": {
5      "id": 5,
6      "description": "Delete profile"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:05:00.000Z",
13    "last_updated_at": "2025-09-25T12:05:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    },
18    "iccid_with_luhn": "89883030000133194051"
19  }
20]

Monitor operations

List operations

Retrieve all operations scheduled for a specific eUICC. Use the q query parameter to filter by action (q=action:3) or status.

Endpoint: GET /api/v1/euicc/{euicc_id}/operation

GET
/api/v1/euicc/:euicc_id/operation
1curl -G https://cdn.emnify.net/api/v1/euicc/123456/operation \
2     -H "Authorization: Bearer <token>" \
3     -d page=1 \
4     -d per_page=25
Try it
Response
1[
2  {
3    "id": "11111111-2222-3333-4444-555555555555",
4    "action": {
5      "id": 3,
6      "description": "Enable profile"
7    },
8    "status": {
9      "id": 1,
10      "description": "Scheduled"
11    },
12    "creation_date": "2025-09-25T12:00:00.000Z",
13    "last_updated_at": "2025-09-25T12:00:00.000Z",
14    "user": {
15      "id": 123456,
16      "name": "John Doe"
17    },
18    "expiry_date": "2025-09-25T12:10:00.000Z",
19    "iccid_with_luhn": "89883030000123456789"
20  }
21]

Get operation details

Retrieve the details and current status of a specific operation.

Endpoint: GET /api/v1/euicc/{euicc_id}/operation/{operation_id}

GET
/api/v1/euicc/:euicc_id/operation/:operation_id
1curl https://cdn.emnify.net/api/v1/euicc/123456/operation/11111144-2222-3333-4444-555555555555 \
2     -H "Authorization: Bearer <token>"
Try it
Response
1{
2  "id": "11111144-2222-3333-4444-555555555555",
3  "action": {
4    "id": 2,
5    "description": "Download profile"
6  },
7  "status": {
8    "id": 2,
9    "description": "Succeeded"
10  },
11  "creation_date": "2025-09-25T12:00:00.000Z",
12  "last_updated_at": "2025-09-25T12:15:00.000Z",
13  "user": {
14    "id": 123456,
15    "name": "John Doe"
16  },
17  "expiry_date": "2025-09-26T12:00:00.000Z",
18  "finalization_date": "2025-09-25T12:15:00.000Z",
19  "iccid_with_luhn": "89883030000133194051"
20}

Operation statuses

IDStatusDescription
1ScheduledOperation is queued and waiting to be sent to the device
2SucceededOperation completed successfully
3FailedOperation failed - check Error Object for more details.
4ExpiredOperation was not executed before the validity_period elapsed
5CanceledOperation was canceled.