Skip to navigation
ServicesPlatformEventsEvent typeseSIM profile lifecycle

eSIM profile lifecycle

Pre-release
API reference

The profile and the outcome are in the event’s detail object.

These events are in pre-release and available only to certain Workspaces. To ask about access, contact emnify Support.

How eSIM profile events work

The emnify SM-DP+ reports each step in the life of an eSIM profile: the download to a device, the installation, and each change the device makes to the profile afterward. The platform turns each report into one event. The event source is SM-DP+ (ID 4).

One event type covers every outcome of an operation. The severity and the alert property tell you the outcome:

Outcomeoutcome in the detail objectSeverityalert
The operation succeededSUCCESSInfo (ID 0)false
The operation succeeded with a warningWARNINGWarn (ID 1)false
The operation failedFAILEDCritical (ID 2)true
The download didn’t complete in timeEXPIREDCritical (ID 2)true

For example, a failed download is an eSIM profile downloaded event with the severity Critical. Check the severity or the outcome before you act on the event type.

The platform reports a successful download, enable, disable, or delete only when the profile status changes. If the SM-DP+ repeats one of these reports, you don’t get a second event. A repeated failure, or a repeated installation result, produces another event.

The sim property identifies the SIM of the profile. The endpoint property identifies the device when the SIM is assigned to one. The event contains no user property. The timestamp is the time the SM-DP+ gives for the operation.

Event description

The description names the profile by its ICCID, and the device by its EID when the platform knows it:

  • Success: eSIM profile with ICCID 89883030001234567894 enabled on EID 89049032001234567890123456789057.
  • Warning: the success sentence, followed by Warning: <reason>.
  • Failure: Failed to download eSIM profile with ICCID 89883030001234567894 on EID 89049032001234567890123456789057: <reason>.

The reason comes from the SM-DP+: its message, or its status codes when it sends no message. A download that doesn’t complete in time has the reason the download timer expired.

Detail object

The detail object of an eSIM profile event contains the following properties:

PropertyTypeDescription
euiccObjectThe eUICC the profile is on: id (Integer) and eid (String). Left out while the SIM isn’t linked to an eUICC.
profileObjectThe eSIM profile: iccid_with_luhn (String), status (Object), profile_type (Object), and name (String). status and profile_type each have an id and a description. status is the profile status after the event, and a failed or expired operation doesn’t change it.
smdp_notificationObjectThe operation and its outcome. category is DOWNLOAD, INSTALL, ENABLE, DISABLE, or DELETE, and outcome is SUCCESS, WARNING, FAILED, or EXPIRED.

The platform leaves out a property that has no value.

eSIM profile downloaded

A device downloaded an eSIM profile from the emnify SM-DP+, or tried to and failed.

A failure can come from one of three steps: the eligibility and retry limit check, the confirmation code check, or the download itself. A download that doesn’t complete in time has the outcome EXPIRED.

eSIM profile installed

A device reported the result of installing an eSIM profile. On success, the profile status is Installed.

eSIM profile enabled

A device enabled an eSIM profile, or tried to and failed. On success, the profile status is Enabled.

eSIM profile disabled

A device disabled an eSIM profile, or tried to and failed.

eSIM profile deleted

A device deleted an eSIM profile, or tried to and failed. On success, the profile status is Deleted.

Examples

{
  "timestamp": "2026-11-04T10:32:18.000Z",
  "alert": false,
  "description": "eSIM profile with ICCID 89883030001234567894 enabled on EID 89049032001234567890123456789057.",
  "id": 2731266482913307,
  "event_type": {
    "id": 85,
    "description": "eSIM profile enabled"
  },
  "event_source": {
    "id": 4,
    "description": "SM-DP+"
  },
  "event_severity": {
    "id": 0,
    "description": "Info"
  },
  "organisation": {
    "id": 14543,
    "name": "Sample Corp"
  },
  "endpoint": {
    "id": 83173458,
    "imei": "3567890123456701",
    "ip_address": "100.64.12.34",
    "name": "Tablet 017",
    "tags": null
  },
  "sim": {
    "iccid": "8988303000123456789",
    "id": 3668977,
    "production_date": "2026-09-14T08:00:00.000Z"
  },
  "imsi": {
    "id": 323245909,
    "import_date": "2026-09-14T08:00:00.000Z",
    "imsi": "001010000000017"
  },
  "detail": {
    "euicc": {
      "id": 42,
      "eid": "89049032001234567890123456789057"
    },
    "profile": {
      "iccid_with_luhn": "89883030001234567894",
      "status": {
        "id": 8,
        "description": "Enabled"
      },
      "profile_type": {
        "id": 3,
        "description": "Consumer eUICC Profile"
      }
    },
    "smdp_notification": {
      "category": "ENABLE",
      "outcome": "SUCCESS"
    }
  }
}
{
  "timestamp": "2026-11-04T09:15:02.000Z",
  "alert": true,
  "description": "Failed to download eSIM profile with ICCID 89883030001234567894 on EID 89049032001234567890123456789057: the confirmation code retries were exceeded.",
  "id": 2731262215748890,
  "event_type": {
    "id": 83,
    "description": "eSIM profile downloaded"
  },
  "event_source": {
    "id": 4,
    "description": "SM-DP+"
  },
  "event_severity": {
    "id": 2,
    "description": "Critical"
  },
  "organisation": {
    "id": 14543,
    "name": "Sample Corp"
  },
  "endpoint": {
    "id": 83173458,
    "imei": "3567890123456701",
    "ip_address": "100.64.12.34",
    "name": "Tablet 017",
    "tags": null
  },
  "sim": {
    "iccid": "8988303000123456789",
    "id": 3668977,
    "production_date": "2026-09-14T08:00:00.000Z"
  },
  "imsi": {
    "id": 323245909,
    "import_date": "2026-09-14T08:00:00.000Z",
    "imsi": "001010000000017"
  },
  "detail": {
    "euicc": {
      "id": 42,
      "eid": "89049032001234567890123456789057"
    },
    "profile": {
      "iccid_with_luhn": "89883030001234567894",
      "status": {
        "id": 5,
        "description": "Released"
      },
      "profile_type": {
        "id": 3,
        "description": "Consumer eUICC Profile"
      }
    },
    "smdp_notification": {
      "category": "DOWNLOAD",
      "outcome": "FAILED"
    }
  }
}