Event Manager for Phone Number Verification



Event Manager is available for all users and companies in the Syniverse Developer Community (SDC).

Market Dynamics

The connected world is evolving at a rapid pace; as is the need for quick access to information relevant to your business. Event Manager helps your organization share and feed information from Syniverse solutions to any company environment connected to the Internet (for example: Your Customer Relationship Management [CRM] system).


Event Manager is a core component of the SDC platform. The purpose of Event Manager is to send alerts from Syniverse solutions back to your environment. With Event Manager, you can automate your system to more efficiently serve your users.

Use Case

Phone Number Verification: Using Event Manager with Phone Number Verification, you can proactively monitor the status of phone numbers. Get an event notification when a phone number status -- such as porting, deactivation or disconnect -- changes. With event notifications, you can update your CRM database in near real-time. When you add in Batch Automation and Media Storage Solution, you can upload a file of numbers to monitor and Event Manager notifies you when the response file is ready to download.

Service Description

Combining Event Manager with PNV gives you the ability to proactively monitor events related to one or more phone numbers. You tell the system which phone number and events to monitor and the system sends you a notification when an event happens. For example: If monitoring a number’s status, the system sends a notification when a status event – such as porting, deactivation or disconnect – happens.

To use Event Manager with PNV, you need to enable Event Subscription Services in your SDC application. Once the service is enabled, you can configure Event Manager. You have the option to configure the service using the SDC or via API calls. Whether you configure the service via the user interface or API, you need to establish your delivery configuration and then subscribe to the Topic | Events you want to be notified of.

Using the interface, you create your delivery configuration and subscription from the Event Manager menu.

Events can be configured in two ways – you can opt for near real-time or scheduled delivery.

Near Real-Time Delivery – with a near real-time delivery configuration, Event Manager sends all events matching your subscription to a defined endpoint as soon as the system detects the event. This endpoint needs to be accessible from the Syniverse Developer Community, otherwise the events cannot be delivered.

The endpoint for the event delivery must accept REST as the delivery protocol. You can throttle event delivery when your defined endpoint(s) cannot accept more than a certain amount of requests in a defined amount of time. Supported delivery formats for near real-time event delivery include: JSON and XML. Once you establish a delivery configuration and mark it "active," the system starts sending events to the active endpoint(s).

Scheduled Delivery – Records all events during a specified time period and stores the events in a file. You can set a schedule through a simple setup that supports a cron statement. Simple schedule options include every: minute, hour, day, week, month and year.

If you turn off Use simple schedule, you can customize the event schedule by entering a cron expression to set your schedule for delivery. Scheduled event delivery only supports JSON file format. Note: If unfamiliar with cron, Syniverse recommends using a simple schedule.


After creating your delivery configuration, you can set an authentication method, which requires authentication before event delivery. You can choose from thee authentication options:

  • None - Events are sent to the endpoint without required authentication.
  • Basic Auth - Authentication is required. The system requests a username and password combination before allowing events to be delivered.
  • OAuth 2.0 - Authentication is required and completed via OAuth2 support. Environments that support OAuth 2.0 authentication can link to Event Manager and, before sending events to the your environment, Event Manager must be authenticated by the end-points. OAuth2 allows you to define how access tokens are generated and received. You can choose from three grant types:
    • Client Credentials - Event Manager uses provided client credentials to request an access token for the connection.
    • Password - Event Manager generates an access token from a username/password combination. Note: This option should be used with care.
    • Refresh Token - Event Manager stores a refresh token, which is used to connect to your environment. You can set the refresh token to timeout at any given time.


With your Delivery Configuration established, you are ready to set up your Subscriptions. Subscriptions configure the topics and event types you want to receive.

When creating a subscription, you can choose from a number of topics. For PNV, you want to select NIS-Events. This brings up a list of events – you can choose All Types or one of the following: Deactivation_event or Truedisconnect_event.

Event Reporting

There are four options to access or view specific events.

  • Event Viewer – you can view all events in your environment, including event status. Within viewer you can choose from four actions:
    • View - Shows specific event information
    • Tracking - Lists event delivery attempts
    • Republish - Provides the option to republish an event
    • Mark as handled - Changes the event status to handled
  • Event Delivery DashboardProvides overall status of delivery configurations receiving events. When many events enter the dashboard, you can sort by pending delivery (or queued), pending retry or have failed.
  • Event SearchYou can search for all events in your environment. For example, you can search for a specific event based on the ID or for a range of events within a specific time frame.
  • Event Buffer FilesShows the status of events marked for scheduled delivery. Files are stored in the Media Storage Service (MSS) and can be downloaded using the URL provided in the event in "MSS-Messages" topic.


To utilize Event Manager services, you need the following:

  • Company environment in Syniverse Developer Community
  • Subscription to Developer Community Gateway services
  • Application with Phone Number Verification and Event Manager activated

Related Services

Currently the Event Manager supports the following services:

  • Chat API Service: Enables companies to send and receive messages, and conduct chats with its end-users via a CRM application or cross-channel call center applications
  • OTT API Service: Supports personalizing messages, and sending and receiving messages to and from end-users utilizing Facebook Messenger and/or WeChat mobile applications
  • SMS API Service: Supports personalizing messages, sending and receiving messages with different content types, recognizing and tracking threads of conversations and conversion events, and providing a higher level of analytical information on communication events.
  • Push API Service: Offers an optional push notification mobile SDK that supports iOS and Android applications and interacts with our REST-based APIs.
  • Voice API Service: Provides a set of calling features and functionalities that allow customers to trigger outbound calling to one or more recipients
  • Batch Automation Service: Processes input files uploaded and stored in the Media Storage Service, and stores the batch process output files in the Media Storage Service for download by the customer
  • Phone Number Verification API Service: Identifies phone numbers with event changes and returns a response via the API.
  • Media Storage Service: Collaborative, trusted file sharing service that enables the exchange of media files between services for batch processing

Example API calls for Event Manager

This page contains a few examples for both:

  • the API calls for Event Manager in cURL.
  • Example event notifications

To see all available APIs please go to the resources page.

Example API Calls

Operation Example Call
Create a Delivery Configuration curl -X POST<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]"<br> -H "Content-Type: application/json"<br> -d '{ "del-cfg-nm":"", "del-prtcl-cd":"REST",<br> "addr":"",<br> "del-fmt-cd":"JSON","is-active":true<br> }'<br> "https://api.syniverse.com/ess/v1/delivery-configurations"
Get Available Topics curl -X GET<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]" "https://api.syniverse.com/ess/v1/topics/"
Create a Topic Subscription curl -X POST<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]"<br> -H "Content-Type: application/json"<br> -d '{<br> "del-cfg-id": "",<br> "start-date": "",<br> "end-date": null<br> }'<br> "https://api.syniverse.com/ess/v1/topics/SCG-Message/subscriptions"
Get All Delivery Configurations curl -X GET<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]" "https://api.syniverse.com/ess/v1/delivery-configurations"
Get Summary of Event Deliveries curl -X GET<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]" "https://api.syniverse.com/ess/v1/event-deliveries/summary"
Get a Count of Unique Phone Numbers Being Monitored for Lifecycle Events
curl -X GET 
-H "Authorization: Bearer [YOUR ACCESS TOKEN]" 

An example JSON Response when only one unique phone number is monitored
{ "topic-name": "NIS-Events", "activeCount": 1 }

Check if a Phone Number is Being Monitored for Lifecycle Events

curl -X GET<br> -H "Authorization: Bearer [YOUR ACCESS TOKEN]" <br> "https://api.syniverse.com/ess/v1/topic-subscriptions/mdn?topicId=NIS-Events&matchingCriteria=number%20=%20%27%2B447860438585%27"

The query url includes two parameters:

The topicID is set to NIS-Events.

The matchingCriteria is set to number = '+447860438585' which is urlencoded to number%20=%20%27%2B447860438585%27 . The phone number is in international format which includes the leading + sign and the country code.
An example JSON Response for the above query is:
{ "paged-result": { "offset": 0, "limit": 50 }, "mdn": "number = '+447860438585'", "topic-name": "NIS-Events", "subscriptions": [ { "delivery-cfg-id": "676", "delivery-cfg-nm": "NumberMonitoring", "events": [ "porting_event" ] } ] }

Example Notifications

Use Case Example Notification
Phone Number Event Notification

Method: POST<br/> Headers   <br/> "X-ESS-EVENT-KEY": "+178XXXXXXXX,",   <br/> "X-ESS-EVENT-TIMESTAMP": "2017-07-12T20:21:00.129Z",   <br/> "CONTENT-TYPE": "application/json; charset=UTF-8"<br/> BODY/PAYLOAD<br/> {"topic":"NIS-Events","attempt":1,"event":{"fld-val-list":{"number":"+178XXXXXXXX","previous_carrier_id":"1025", "previous_carrier_name":"AT@$# T WIRELESS","tracking_id":"1655272074","deactivation_date":"2017-06-03T04:00:00Z"}, "evt-tp":"deactivation_event","timestamp":"2017-07-12T20:21:00.129Z"},"event-id":"d0qgWF8ERLGn_7JJOGhqNQ"}

True Disconnect Report ready for download includes the file uri to download the report Method: POST<br> Content : application/json Charset= UTF-8<br> BODY/PAYLOAD<br> { "topic": "MSS-Messages", "attempt": 1, "event": {"fld-val-list": {"creation_time": "2017-10-19T18:46:32Z", "file_retention_time": 30, "app_name": "ESS", "company-id": 3743, "modified_time": "2017-10-19T18:46:33Z", "file_uri": "https://lab-api.syniverse.com/mediastorage/v1/files/0d1a9e0f-934e-408b-868c-063653f21e3f/content", "file_status": "COMPLETE", "file_name": "TRUE_DISCONNECT_EVENT-092017-20171019184626.dat", "file_id": "0d1a9e0f-934e-408b-868c-063653f21e3f", "file_tags": "ESS", "expire_time": "2017-11-18T18:46:32Z", "file_size": 44 }, "evt-tp": "event_file_complete", "timestamp": "2017-10-19T18:46:33.491Z" }, "event-id": "iagOyZRqRFq7aHgDspCTwg" }