> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emnify.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emnify.com/_mcp/server. > Event API reference with comprehensive event types, severities, sources, and detailed object schemas for network and API events. The following table shows the properties of a generic event. These properties are included in *all* events: | Property | Type | Description | | :--------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Long (64-bit integer) | A unique numeric identifier of the event. If multiple events with same id are received (for example, due to transmission errors), these should be treated as duplicates by the receiver. | | `timestamp` | Timestamp (UTC) | Date/time when this event occurred. | | `event_type` | JSON object | Type of the event (see [Event type object](#event-type-object)). | | `description` | String | Human readable description of the event | | `event_severity` | JSON object | Severity of the event (see [Event severity object](#event-severity-object)). | | `alert` | Boolean | Event is a candidate to be alerted to a user. | | `event_source` | JSON object | Source of the event (see [Event source object](#event-source-object)). | | `organisation` | JSON object | Organization associated with the event (see [Organization object](#organization-object)). | | `user` | Object | User details (see [User object](#user-object)). | | `endpoint` | JSON object | Device details (see [Endpoint object](#endpoint-object)). | | `sim` | JSON object | SIM details (see [SIM object](#sim-object)). | | `imsi` | JSON object | IMSI details of that SIM (see [IMSI object](#imsi-object)). In the case of multi-IMSI configuration, events only show the most recently active IMSI. | | `detail` | Object | Optional additional information (see [Detail object](#detail-object)). | Depending on the event type, some properties don't apply. For example, network-related events (for example, a device connected to the network) contain endpoint, SIM, and IMSI data. The detail object have the mobile network operator (MNO) details but won't contain user data. Meanwhile, events affecting a user (for example, authentication issues) contain user and trusted device data but no network-related data. Example - SIM data available: ```json "sim": {"sim_id" : "..."} ``` Example - SIM data not available: ```json "sim": null ``` ## Event type object | Property | Type | Description | | :------------ | :------ | :----------------------------------- | | `id` | Integer | Unique identifier of the event type. | | `description` | String | Description of the event type. | The following table describes currently available event types (`event_type`): | ID | Description | | :- | :-------------------------------------- | | 0 | Generic | | 1 | Update location | | 2 | Update GPRS location | | 3 | Create PDP Context | | 4 | Update PDP Context | | 5 | Delete PDP Context | | 6 | User authentication failed | | 7 | Application authentication failed | | 8 | SIM activation | | 9 | SIM suspension | | 10 | SIM deletion | | 11 | Endpoint blocked | | 12 | Organisation blocked | | 13 | Support Access | | 14 | Multi-factor Authentication | | 15 | Purge location | | 16 | Purge GPRS location | | 17 | Self-Signup | | 18 | Quota threshold reached | | 19 | Quota used up | | 20 | SMS quota threshold reached | | 21 | SMS quota used up | | 22 | CloudConnect TGW Resource Share created | | 23 | CloudConnect TGW available | | 24 | CloudConnect VPN breakout available | | 25 | CloudConnect TGW breakout terminated | | 26 | CloudConnect VPN breakout terminated | | 27 | CloudConnect Connection State Changed | | 28 | OpenVPN connect | | 29 | OpenVPN disconnect | | 30 | OpenVPN authentication | | 31 | Organisation updated | | 32 | Billing configuration updated | | 33 | Platform package updated | | 34 | Data plan updated | | 35 | Payment | | 36 | User invited | | 37 | Password reset requested | | 38 | Order submitted | | 39 | Order updated | | 40 | User verification requested | | 41 | User verified | | 42 | Endpoint enabled | | 43 | Endpoint disabled | | 44 | SIM issued | | 45 | SIM factory test | | 46 | User deleted | | 47 | User federation activated | | 48 | SIM registration | | 49 | Device offline (placeholder) | | 50 | SIM Released | | 51 | SIM Assigned | | 52 | Data quota enabled | | 53 | Data quota disabled | | 54 | SMS quota enabled | | 55 | SMS quota disabled | | 56 | Data quota assigned | | 57 | Data quota deleted | | 58 | SMS quota assigned | | 59 | SMS quota deleted | | 60 | Data quota expired | | 61 | SMS quota expired | | 62 | Default inclusive volume updated | | 63 | Monthly order limit threshold reached | | 64 | Monthly order limit reached | | 65 | Endpoint data traffic limit warning | | 66 | SMS MO P2P limit reached | | 67 | User switched workspaces | | 68 | Reset connectivity | | 69 | SIM migration | | 70 | Endpoint limit extension | | 72 | Custom | | 76 | Custom role created | | 77 | Custom role edited | | 78 | Custom role deleted | | 79 | User role assigned | | 80 | User role unassigned | > **Note** > > Event type `Device offline` (ID `49`) is a placeholder. > The API lists it among the event types, but the platform never sends events of this type. All [custom events](/system-events/event-types/custom-events) share the event type `Custom` (ID `72`). The `template_id` property of the [detail object](#detail-object) identifies which custom event was triggered. > **Note** > > Event history is stored for 30 days. ## Event severity object | Property | Type | Description | | :------------ | :------ | :--------------------------------------- | | `id` | Integer | Unique identifier of the event severity. | | `description` | String | Description of the event severity. | The following table describes currently available event severities (`event_severity`): | ID | Description | | :- | :---------- | | 0 | Info | | 1 | Warn | | 2 | Critical | ## Event source object | Property | Type | Description | | :------------ | :------ | :------------------------------------- | | `id` | Integer | Unique identifier of the event source. | | `description` | String | Description of the event source. | The following table describes currently available event sources (`event_source`): | ID | Description | | :- | :------------- | | 0 | Network | | 1 | Policy Control | | 2 | API | | 3 | Semantic | Events with the source `Semantic` (ID `3`) are generated by the emnify event processing engine, which evaluates the conditions you configure for [custom events](/system-events/event-types/custom-events). ## Organization object | Property | Type | Description | | :------- | :------ | :------------------------------------- | | `id` | Integer | Unique identifier of the organization. | | `name` | String | Name of the organization. | ## User object | Property | Type | Description | | :--------- | :------ | :------------------------------------- | | `id` | Integer | Unique identifier of the user. | | `username` | String | Username (for example, email address). | | `name` | String | Actual name of the user. | ## Endpoint object | Property | Type | Description | | :----------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Integer | Unique identifier of the device. | | `name` | String | Configured name of the device. | | `ip_address` | String | IP address assigned to the device. | | `tags` | String | Tags assigned to the device. | | `imei` | String | 16-digit long code indicating the International Mobile Equipment Identity - Software Version. [Differs from a standard IMEI](https://www.emnify.com/blog/imei-number) in that the last two numbers identify the software/firmware version. | ## SIM object | Property | Type | Description | | :---------------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iccid_with_luhn` | String | [Integrated circuit card identifier](https://www.emnify.com/iot-glossary#iccid) *with* the final [Luhn checksum digit](https://www.emnify.com/iot-glossary#luhn-checksum-digit) | | `iccid` | String | [Integrated circuit card identifier](https://www.emnify.com/iot-glossary#iccid) *without* the final [Luhn checksum digit](https://www.emnify.com/iot-glossary#luhn-checksum-digit) | | `msisdn` | String | [Mobile Station International Subscriber Directory Number (MSISDN)](https://www.emnify.com/iot-glossary#msisdn). | | `production_date` | Timestamp (UTC) | Date and time the SIM chip was produced. | | `id` | Integer | Unique identifier of the SIM. | ## IMSI object | Property | Type | Description | | :------------ | :-------------- | :----------------------------------------------- | | `id` | Integer | Unique identifier of the IMSI. | | `imsi` | String | International Mobile Subscriber Identity (IMSI). | | `import_date` | Timestamp (UTC) | Date and time the IMSI was provisioned. | ## Detail object Some events may contain additional data added as a nested object called `detail`. This object includes specific information depending on the event type, event source, and event severity (for example, the country, details about Cloud Connect, trusted device data, etc.). Events with event type `Network` (id = `0`) may contain detailed information about the mobile network operator (MNO): | Property | Type | Description | | :------------ | :---------- | :--------------------------------------------------------------------------- | | `id` | Integer | Unique identifier of the MNO. | | `name` | String | Name of the MNO. | | `country` | JSON object | Country of the MNO (see [Country object](#country-object)). | | `pdp_context` | JSON object | PDP context details (see [PDP context object](#pdp-context-object)). | | `volume` | JSON object | Volume consumed in a PDP context (see [Volume object](#volume-object)). | | `tapcode` | JSON array | List of the MNO tap codes (see [Tap code array](#tap-code-array)). | | `mnc` | JSON array | List of mobile network codes (MNC) of the MNO (see [MNC array](#mnc-array)). | | `session_id` | String | Session UUID for correlating PDP context events and usage record objects. | Events with event type `API` (id = `2`) may contain information from the API. The following table shows examples: | Property | Type | Description | | :----------------- | :---------- | :---------------------------------------------------------------------------------- | | `trusted_device` | JSON object | Trusted device of the user (see [Trusted device object](#trusted-device-object)). | | `support_username` | String | Username of the support user. | | `support_user_org` | JSON object | Organization of the support user (see [Organization object](#organization-object)). | | `target_username` | String | Username of the target user. | Events with event source `Semantic` (id = `3`) contain the parameters of the triggered custom event, such as the template it's based on and the configured thresholds. For the full list, see [Custom events](/system-events/event-types/custom-events). ### PDP context object The PDP context is a data connection that allows the device to transmit IP data over the network. The PDP context object contains information about the devices' connection: | Property | Type | Description | | :------------------------------ | :-------------- | :--------------------------------------------------------------------------------------------------------- | | `pdp_context_id` | Integer | Unique identifier of this PDP context. | | `tariff_profile_id` | Integer | Unique identifier of the tariff profile assigned to the device. | | `tariff_id` | Integer | Unique identifier of the tariff used by the device. | | `ratezone_id` | Integer | Unique identifier of the coverage area used by the device. | | `operator_id` | Integer | Unique identifier of the operator used by the device. | | `sac` | Integer | Service Area Code (SAC). | | `rac` | Integer | Routing Area Code (RAC). | | `region` | String | Region where the data plane is located. | | `rat_type` | Integer | Radio Access Type (RAT). Corresponding IDs listed below. | | `nsapi` | Integer | Network Service Access Point Identifier (NSAPI). | | `mcc` | String | Mobile Country Code (MCC). | | `mnc` | String | Mobile Network Code (MNC). | | `lac` | Integer | Location Area Code (LAC). | | `ggsn_control_plane_ip_address` | String | IP address of the GGSN/PGW control plane. | | `ggsn_data_plane_ip_address` | String | IP address of the GGSN/PGW data plane. | | `sgsn_control_plane_ip_address` | String | IP address of the SGSN/SGW control plane. | | `sgsn_data_plane_ip_address` | String | IP address of the SGSN/SGW data plane. | | `breakout_ip` | String | IP address used for Internet breakout. | | `ue_ip_address` | String | IP address assigned to the device. | | `imeisv` | String | International Mobile Equipment Identity - Software Version (IMEISV). | | `gtp_version` | String | GPRS Tunnelling Protocol (GTP) version. This value is either `1` or `2`. | | `tunnel_created` | Timestamp (UTC) | Date and time the PDP context was created. | | `ci` | Integer | Cell Identification (CI). | | `apn` | String | Access Point Name (APN). | | `tx_teid_control_plane` | Integer | Tunnel Endpoint Identifier (TEID) of the receiving control plane. | | `tx_teid_data_plane` | Integer | Tunnel Endpoint Identifier (TEID) of the receiving data plane. | | `rx_teid` | Integer | Tunnel Endpoint Identifier (TEID) of the sending entity. | | `imsi` | String | International Mobile Subscriber Identity (IMSI). The unique number identifying the active IMSI of the SIM. | Radio Access Type (RAT) IDs correspond to the following values: | ID | Value | | :- | :----- | | 1 | 3G | | 2 | 2G | | 3 | WLAN | | 4 | GAN | | 5 | HSPA+ | | 6 | 4G | | 8 | NB-IoT | | 9 | LTE-M | | 10 | 5G | ### Country object | Property | Type | Description | | :------------- | :------ | :-------------------------------- | | `id` | Integer | Unique identifier of the country. | | `name` | String | Name of country. | | `country_code` | String | Numeric country code. | | `mcc` | String | Mobile Country Code (MCC). | | `iso_code` | String | ISO code. | ### Volume object | Property | Type | Description | | :------------- | :------------------------------------- | :----------------------- | | `volume.rx` | Decimal(14,6) (up to 6 decimal places) | Downstream volume in MB. | | `volume.tx` | Decimal(14,6) (up to 6 decimal places) | Upstream volume in MB. | | `volume.total` | Decimal(14,6) (up to 6 decimal places) | Total volume. | ### Tap code array | Property | Type | Description | | :-------- | :------ | :------------------------------------------------------ | | `id` | Integer | Unique identifier of this tap code. | | `tapcode` | String | Tap code assigned to the mobile network operator (MNO). | ### MNC array | Property | Type | Description | | :------- | :------ | :-------------------------------------------------- | | `id` | Integer | Unique identifier of the mobile network code (MNC). | | `mnc` | String | MNC assigned to the mobile network operator (MNO). | ### Trusted device object | Property | Type | Description | | :----------------- | :-------------- | :--------------------------------------- | | `id` | Integer | Unique identifier of the trusted device. | | `operating_system` | String | Operating system of the trusted device. | | `browser` | String | Browser of the trusted device. | | `activation_date` | Timestamp (UTC) | Activation date of the trusted device. | ## Example event **Sample event showing PDP context deletion:**\ For more examples, see the API specification for [`/api/v1/event`](/developers/api/events/get-events). ```json maxLines=15 [ { "timestamp": "2015-07-16 12:07:09", "alert": true, "description": "PDP Context deleted.", "id": 69535, "event_type":{ "description": "Delete PDP Context", "id": 4 }, "event_source": { "name": "Network", "id": 0 }, "event_severity": { "description": "INFO", "id": 0 }, "organisation": { "name": "Organisation_Name", "id": 2 }, "endpoint": { "name": "Monitoring201", "tags": "Monitoring", "ip_address": "10.199.6.39", "imei": null, "id": 69 }, "sim": { "iccid": "8988317000000000100", "production_date": "2014-12-17 13:26:13", "id": 110 }, "imsi": { "imsi": "901430000000114", "import_date": "2014-12-17 13:26:08", "id": 110 } } ] ``` ## Compatibility notes The Event Bus is under active development. It is regularly updated for performance and quality improvements so that users of the platform may gain rich insights into event data when using the [Event API](/developers/api/events) or the [Data Streamer](/developers/reference/data-streamer). Users who have built custom integrations should expect that additional data may be added in the future. Mature and tested libraries designed for parsing or reading JSON should be used for custom integrations to ensure compatibility. ## Event data properties Data types are referred to in the following sections to assist with integration or database schemas. They should be interpreted as follows: | Type | Description | | :-------------------- | :-------------------------------------------------------------------------------------------------- | | INTEGER | An integer value usually used for entity IDs, won't exceed 32-bit values. | | LONG (64 bit integer) | For event IDs, a long value should be expected. | | BOOLEAN | `true` or `false` | | STRING | A string value enclosed in `" "` double quotation characters. | | DECIMAL(14,6) | Used for data volume measurements (`volume.total`, `volume.tx`, `volume.rx`) with 6 decimal places. | | DECIMAL(14,10) | Cost calculation (`cost` property) may have up to 10 decimal places. | | TIMESTAMP | Timestamp property in UTC enclosed in `"` double quotation characters. |