Work with system events

There are three ways you can access and trigger available events:

• Data Streamer
• Event API
• emnify Portal

Data Streamer

The emnify Data Streamer allows you to configure data streams that capture events generated by the emnify system. These events can include billing-related updates, SIM orders, and other operations your users perform.

You gain full network transparency by leveraging integrations to identify and address issues quickly. Additionally, you can use the provided information to develop your applications or business logic. These integrations offer valuable insights for IoT remote monitoring, anomaly detection, detailed service usage data (data and SMS), and cost per device.

tip

See the Data Streamer documentation to learn more about its benefits and how to get started.

Manage event data streams in the Portal

To manage your data streams, log in to your emnify Portal account. Then, navigate to the Data Streams section of the Integrations page.

If no data streams are configured, the Data Streams panel displays all available connection types as tiles.

If you already have a data stream configured, the panel displays all existing streams, ordered by creation date (newest on the top). This list view can be used to gain an overview of the current states of different data streams.

Data streams marked as Running are properly operating. Failed streams exhibit an Error status. Paused streams are marked as Paused.

The Details button allows you to inspect the configuration of the specific stream.

info

You can distinguish event data streams by checking if the Stream Type on a specific data stream is set to Stream events.

The Data Streamer can apply filtering for event data streams based on event types. Under Event Options, you can choose to Stream all events or Stream specific events only. Selecting the latter displays a searchable dropdown listing all event types available as filters.

tip

Using the Portal, you can also create, update, and delete data streams. Learn more in the Data Streamer usage documentation.

Event API

The emnify REST API provides a variety of HTTP requests for integrating several emnify services into your application, including the ability to trigger and monitor events.

The Event API specifically allows you to search for recent events and supports various types of result filtering.

warning

For events, the emnify REST API uses a pull architecture, which means you're responsible for requesting updates and retrieving new events. If you prefer real-time updates, consider using the emnify Data Streamer.

Authentication

To use the emnify API, you must authenticate with an authentication token. emnify uses JSON Web Tokens (JWTs) for the authentication tokens.

tip

The Getting Started guide in the emnify REST API Documentation provides step-by-step instructions for retrieving your authentication token.

Specification and documentation

The emnify API is based on the OpenAPI Specification 3.0 (OAS3). We also offer interactive API documentation.

tip

Prior OpenAPI knowledge isn't necessary to work with the emnify API. However, understanding how an OpenAPI Specification is structured could help you navigate the documentation.

The Events Reference page in the emnify REST API Documentation provides detailed information about the event structure and common elements you'll encounter using the Event API.

Retrieve events with the Event API

The following entry points are available for retrieving a list of the events or event types available to your organization:

Method	Entry point	Description
GET	/api/v1/event	Returns the list of events, filtered, sorted, and paged according to query parameters.
GET	/api/v1/event/type	Provides the list of event_types (lookup).

You can also list events for specific endpoints, SIMs, or users using the following entry points. These event lists can be filtered, sorted, and paged according to query parameters.

Method	Entry point	Description
GET	/api/v1/endpoint/{endpoint_id}/event	Returns the list of endpoint events.
GET	/api/v1/sim/{sim_id}/event	Returns the list of SIM events.
GET	/api/v1/user/{user_id}/event	Returns the list of user events.

emnify Portal

There are several ways to view or trigger events within the emnify Portal.

Events in the Portal

Here's where you can find event information in the Portal:

Destination	Event information
Dashboard	Overview of all event activity within your organization.
Connected Devices > Details > Events	List of triggered events for a particular device (also referred to as an "endpoint").
SIM Inventory > Details > Events	List of triggered events for a particular SIM card.

info

Any events triggered in the Portal show API as the event source.

Available data for individual events

No matter where you view events in the Portal, you'll have access to the following information for each event.

Property	Description
Severity	The event severity.
Date	A timestamp the event was triggered. By default, the Portal shows the relative date (for example, "a day ago," "15 days ago," "a month ago"). Pressing the clock icon shows an absolute date value in the MMMM dd, yyyy hh:mm a format.
Event Source	Which system triggered the event.
Event Type	Name of the triggered event (the description value in the Event Type Object). This field also indicates the network generation (4G, 5G, etc.) for specific events, like PDP context lifecycles.
Device	Name of the device impacted by the event (the name value from the Endpoint Object). This name often links to the device's entry on the Connected Devices page of the emnify Portal.
Operator	Which Mobile Network Operator (MNO) the device is currently roaming on (for example, Vodafone, AT&T). Only listed for relevant network events.
Country	The country where the MNO listed in the Operator field is providing the cellular service.
ID	A generated unique identifier for the event.
Description	What happened, why (in some cases), and any additional details associated with the event type.