Events | emnify Documentation

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).
`description`	String	Human readable description of the event
`event_severity`	JSON object	Severity of the event (see 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).
`organisation`	JSON object	Organization associated with the event (see Organization object).
`user`	Object	User details (see User object).
`endpoint`	JSON object	Device details (see Endpoint object).
`sim`	JSON object	SIM details (see SIM object).
`imsi`	JSON object	IMSI details of that SIM (see 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).

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:

1 "sim": {"sim_id" : "..."}

Example - SIM data not available:

1  "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
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

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

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 in that the last two numbers identify the software/firmware version.

SIM object

Property	Type	Description
`iccid`	String	Integrated circuit card identifier without the final Luhn checksum digit
`msisdn`	String	Mobile Station International Subscriber Directory Number (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 CloudConnect, 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).
`pdp_context`	JSON object	PDP context details (see PDP context object).
`volume`	JSON object	Volume consumed in a PDP context (see Volume object).
`tapcode`	JSON array	List of the MNO tap codes (see Tap code array).
`mnc`	JSON array	List of mobile network codes (MNC) of the MNO (see 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).
`support_username`	String	Username of the support user.
`support_user_org`	JSON object	Organization of the support user (see Organization object).
`target_username`	String	Username of the target user.

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.

1 [
2   {
3     "timestamp": "2015-07-16 12:07:09",
4     "alert": true,
5     "description": "PDP Context deleted.",
6     "id": 69535,
7     "event_type":{
8       "description": "Delete PDP Context",
9       "id": 4
10     },
11     "event_source": {
12       "name": "Network",
13       "id": 0
14     },
15     "event_severity": {
16       "description": "INFO",
17       "id": 0
18     },
19     "organisation": {
20       "name": "Organisation_Name",
21       "id": 2
22     },
23     "endpoint": {
24       "name": "Monitoring201",
25       "tags": "Monitoring",
26       "ip_address": "10.199.6.39",
27       "imei": null,
28       "id": 69
29     },
30     "sim": {
31       "iccid": "8988317000000000100",
32       "production_date": "2014-12-17 13:26:13",
33       "id": 110
34     },
35     "imsi": {
36       "imsi": "901430000000114",
37       "import_date": "2014-12-17 13:26:08",
38       "id": 110
39     }
40   }
41 ]

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 or the 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.