Phone Number Verification User Guide
Introduction
Mobile phones have become, for many, an essential part of daily life – linking families, linking business to customers, linking government to constituent and even linking stranger to stranger via communities of mutual interest. Businesses looking to optimize their customer relationship via text messaging can take advantage of:
- Direct communication that is more likely to be noticed, feels less invasive and more likely to get a response
- Convenient communication – a text can be sent from anywhere, at any time.
- Reach further and across demographics – SMS text messaging is a fast, efficient way to reach your audience.
While text messaging is an outstanding way to connect with your customer; you are also responsible for ensuring protection of consumer privacy. The Telephone Consumer Protection Act (TCPA) in the United States is just one example of regulations in place to ensure companies gain explicit written consent from the consumer before sending voice or text messages.
Syniverse can help you balance getting the most out of text messaging while managing your contact database to ensure privacy. Our product, Phone Number Verification, helps you manage the phone numbers in your database to ensure a number has not been reassigned to another user after the original opt-in date.
Phone Number Verification Service Overview
Syniverse Phone Number Verification is a REST-based API service that enables you to identify the current carrier (i.e. message routing), determine if a phone number is text-message enabled (Mobile Marketing campaigns) or categorize a "do-not-call" list for recycled numbers. Batch processing of mobile number databases is supported using the Batch Automation and Media Storage services. With our Event Manager service, you can also proactively monitor phone number changes such as deactivation, porting and disconnect.
The purpose of Phone Number Verification is to look up phone numbers and return a response (or with monitoring, a phone number event/change) via the API.
You can:
- Perform a Single-Number Look-up: Enter a single number directly into the API call and receive a response back with the necessary information about that number.
- Perform a Batch File Look-up: Enter multiple numbers into a formatted TXT file and in E.164 standard (+12122223333) and receive a response file back with information for all numbers in the file.
- Perform Monitoring: Proactively monitor phone numbers via the Event Manager service (see Related Services) and get notified when a phone number event occurs.
Getting Started
To begin using Phone Number Verification, you need four things: A Syniverse Developer Community (SDC) account, enabled service offerings, an application and an access token.
- A Syniverse Developer Community Account – Sign up for an account at https://developer.syniverse.com/. You must request a postpaid account. This postpaid account uses the same Bearer Token as your prepaid/trial account. When requesting the postpaid account, you must accept the Terms and Conditions for using the SDC portal to be production ready. Once requested, the postpaid account request is reviewed by the Syniverse Legal and Finance departments and then implemented. The process takes about three weeks from request to finish. Once postpaid is set up, you can reset the bearer token.
- Enabled Service Offerings for Phone Number Verification and Developer Community Gateway.
Note: For Canada PNV, you are required to be whitelisted by the authorities of that country to receive PNV attributes for Canadian phone numbers. If no whitelisting is present, the default response from the PNV platform is to return an “authorization is required” error.
To enable a service offering:
-
- Go to the Service Offerings tab.
- Click Phone Number Verification Service. The details and pricing page displays.
- Click the arrow to expand Subscriptions.
- Click Subscribe … and a pop-up displays.
- Select your Account from the drop-down.
- Click Confirm.
- An Application with enabled APIs – To enable the APIs, you create a new application or edit an existing one.
- Click Create New or click on the application name to edit an existing application.
- Click on the button to toggle SDC Gateway Services and Phone Number Verification Service to ON.
- Click Save
- An Access Token. The access token displays under Auth Keys
With these four things in place, you are ready to perform a lookup.
Understanding Feature Sets
Before you perform a lookup, it’s important to understand the feature sets the service offers. Phone number verification offers multiple feature sets – premium, standard and legacy – at varying price points. We have evolved our feature sets over time, but have retained legacy feature sets for backwards compatibility.
Features Sets are split between Recommended Feature Sets - these are feature sets which we recommend that customers use; and Legacy Feature Sets - we no longer recommend new customers use these feature sets, but we still support them for existing customers.
Note: If the request does not specify a feature set, the default feature set is the legacy premium de-activation (fs1). This means if you do not specify the standard or legacy feature set, you are billed at the premium rate. In order to query disconnection data then the premium disconnection (fs5) feature set should be used, by specifying fs5 in the query or batch job. For more information on pricing, please contact your account manager.
Recommended Feature Sets
Standard (fs2)
This Standard feature set (fs2) is available for global numbers. When using this feature set, you must specify fs2 in the request. This feature set includes the number, validity and carrier information.
Regulations require you to be whitelisted to look up Canadian numbers. If not whitelisted, an authorization error is returned (i.e. Canadian Number – further authorization is required).
Premium Disconnection (fs5) (for United States only)
This premium feature set is available for US numbers only. When using this feature set, you must specify fs5 in the request.
This is the recommended feature set for US customers as it provides additional information enabling better management of US mobile numbers in their subscriber databases.
As well as standard information, disconnect data is also provided. This enables customers to remove mobile numbers which are likely to be re-assigned to new user. This reduces cost, end user frustration.
The disconnect data feed provides key improvements to free de-activation data. By combining multiple data sources, it filters out de-activated mobile numbers which will not be re-assigned, such as mobile numbers which are being ported between carriers.
This minimizes disruption to ported users and reduces re-acquistion costs.
Legacy Feature Sets
These feature sets are provided for backwards compatibility purposes for existing customers. All new customers should use the recommended feature sets above.
Legacy (fs23)
The Legacy feature set (fs23) is available for global numbers. When using this feature set, you must specify fs23 in the request.
Legacy Premium De-activation (fs1) (for United States numbers only)
The Premium feature set (fs1) is available for lookup of United States numbers. This feature set includes the number, validity and carrier information and supports additional deactivation attributes for (US numbers). As the default feature set, you are not required to specify the feature set in your request.
Supported Attributes by Feature Set
The table below lists all supported attributes per feature set.
Standard (fs2) |
Premium Disconnect (fs5) |
Legacy (fs23) |
Legacy Premium De-activation (fs1) |
|
number |
number |
number |
number |
|
validity |
Validity |
validity |
validity |
|
carrier_id |
carrier_id |
carrier_id |
carrier_id |
|
carrier_name |
carrier_name |
carrier_name |
carrier_name |
|
number_type |
number_type |
number_type |
number_type |
|
country_iso_code |
country_iso_code |
country |
country_iso_code |
|
country |
Country |
porting_status |
country |
|
carrier_mcc |
carrier_mcc |
carrier_mcc |
carrier_mcc |
|
carrier_mnc |
carrier_mnc |
carrier_mnc |
carrier_mnc |
|
ext_trx_id |
last_known_event |
nisds |
account_type (no longer populated) |
|
ext_reseller_cust_id |
disconnect_date |
deactivation_detail carrier_id carrier_name deactivation_date |
last_known_event |
|
tracking_id |
ext_trx_id |
ext_trx_id |
porting_date (no longer populated) |
|
ext_reseller_cust_id |
ext_reseller_cust_id |
previous_carrier_id |
|
|
tracking_id |
tracking_id |
previous_carrier_name |
|
|
deactivation_date |
|||
|
ext_trx_id |
|||
|
ext_reseller_cust_id |
|||
|
tracking_id |
API Specification
This section describes the available attributes when performing a lookup and provides request response examples.
Request Attribute Details
HTTP POST Request for Single Number Lookup
URL https://api.syniverse.com/numberidentity/v3/lookup
Defaults to fs1
Header Attributes
Attribute |
Expected Value |
Mandatory? |
|
content-type |
application/json |
Yes |
|
int-appId |
XXXX (for example: 2233) |
No |
|
int-apild |
XXX (for example: 123) |
No |
|
source-system |
BMS |
No |
|
Int_trx_id |
uid |
No |
|
Authorization |
Bearer <Customer_Unique_Identifier> |
Yes |
|
ext_trx_id |
<Custom_Value> |
No |
|
ext_reseller_cust_id |
<Custom_Value> |
No |
Request Attributes
Attribute |
Format |
Mandatory? |
Length |
Description |
|
phone_number |
E.164 format |
Yes |
15 |
number in international format with a leading +, i.e. +44 7860 123 456 |
|
feature |
Free Format Text |
No |
NA |
Allowed values: fs1, fs2,fs23, fs5 Default value: fs1 |
Response Attributes
deactivation_date (USA/premium only)
Attribute |
Format |
Description |
|
number |
Attribute. String in E.164 format. Max length is 20 |
Telephone number. For example: +12125551212 |
|
validity |
Attribute. String. Max length of 5 |
This attribute indicates if the number is part of a valid line range of numbers. Values: true or false |
|
carrier_id |
Attribute. String. Max length of 15 |
Carrier identified or the carrier serving the phone number. |
|
carrier_name |
Attribute. String. Max length of 256 |
Name of carrier serving the phone number |
|
number_type (VOIP only available for United States) |
Attribute. String. Max length of 2 |
Type of phone number: M (mobile), L (Landline), VM (VOIP Mobile), VL (VOIP Landline) and empty value if number is not valid or if number_type is not known. |
|
country_iso_code |
Attribute. String. Max length of 2 |
The 3 letter ISO code of the country |
|
country |
Attribute. Max length is 256. |
Name of the country the phone number belongs to |
|
carrier_mcc |
Attribute. String. Max length of 3 |
Mobile country code of carrier serving the phone number |
|
carrier_mnc |
Attribute. String. Max length of 3 |
Mobile network code of carrier serving the phone number |
|
account_type (USA/premium only) |
Attribute. String. Max length of 15 |
Empty. This field will no longer be supported, and will always be empty. The attribute is left in place for legacy customers who do not want to change their API integration. . |
|
last_known_event (USA/premium only) |
Attribute. String. Max length of 12 |
Most recent activity on the phone number. Allowed values are ported, deactivated or none. Below attributes are selectively reported based on the last known event type |
|
Porting status (USA/legacy only for fs23) |
Attribute. String. Max length of 5 |
Indicates if a number has been ported in its lifetime (TRUE/FALSE) |
|
porting_date (USA/premium only) |
Attribute. Date. Max length of 20 |
Empty. This field will no longer be supported, and will always be empty. The attribute is left in place for legacy customers who do not want to update their API integration. |
|
previous_carrier_id (USA/premium only) |
Attribute. String. Max length of 15 |
Identifier for the carrier previously serving the phone number. |
|
previous_carrier_name (USA/premium only) |
Attribute. String. Max length of 256 |
Name of the carrier previously serving the phone number. |
|
deactivation_date (US/CAN Premium only) |
Attribute. Date. Max length of 20 |
Date when phone number was deactivated. Date format: “YYYY-MM-DDThh:mm:ssZ” |
|
disconnect_date (US Premium only) |
Attribute. Date. Max length of 20 |
Date when phone number was disconnected. Date format: “YYYY-MM-DDThh:mm:ssZ” |
| ext_trx_id |
Attribute. Max length is 64 |
This is the unique identifier sent by the customer in the request header to track the request/response chain. The value of this attribute is extracted from the header of the POST request. |
|
ext_reseller_cust_id |
Attribute. Max length is 64 |
This attribute represents the customer of our customer using the service. The value is extracted from the POST request header. |
|
tracking_id |
Attribute. String. Max length of 25 |
Generated unique identifier to track the request response chain. |
Sample Request Responses
Legacy Premium Feature Set (fs1)
The following is an example using the default, premium feature set.
n.b. New customers should use the Premium Disconnection Feature set (fs5) instead of this feasureset.
POST Request
URL: https://api.syniverse.com/numberidentity/v3/lookup
Request headers
content-type: application/json
ext_trx_id=Testqa
ext_reseller_cust_id=Reseller_cust_id
authorization= Bearer xxxxxxxxxxxxxxxxxxxxx
Payload
{"phone_number":"+1XXXXXXXX70","feature":"fs1"}
<strong>or</strong>
{"phone_number":"+1XXXXXXXX70"}
Response(for POST)
Following sample responses illustrate three possible outcomes: Case 1, Case 2 and Case 3.
Case 1
Outcome for a recently ported (possibly even with a deactivation in the past) number.
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id":"1234",
"carrier_name": "SPRINT PCS",
"country_iso_code": "USA",
"country": "United States",
"number_type": "M",
"carrier_mcc": "123",
"carrier_mnc": "214",
"account_type":"",
"last_known_event": "Deactivated",
"porting_date": "2018-08-10T00:00Z",
"previous_carrier_id": "8401",
"previous_carrier_name": "VERIZON"
},
"tracking_id": "101580180391472739483159",
"ext_trx_id": "Testqa",
"ext_reseller_cust_id": "Reseller_cust_id"
}
Outcome for recently deactivated but not ported number.
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id": "1125",
"carrier_name": "VERIZON WIRELESS",
"number_type": "M",
"country_iso_code": "USA",
"country": "United States",
"carrier_mcc": "310",
"carrier_mnc": "012",
"account_type": "",
"last_known_event": "Deactivated",
"previous_carrier_id": "1125",
"previous_carrier_name": "VERIZON WIRELESS",
"deactivation_date": "2018-08-10T00:00Z"
},
"ext_trx_id": "1234567890123456",
"tracking_id": "211010189721534845085726"
}
Case 3
Outcome for a number without any deactivation or porting history
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id":"1234",
"carrier_name": "SPRINT PCS",
"country_iso_code": "USA",
"country": "United States",
"number_type": "M",
"carrier_mcc": "123",
"carrier_mnc": "214",
"account_type":"Prepaid",
"last_known_event": "None"
},
"tracking_id": "101580180391472739483159",
"ext_trx_id": "Testqa",
"ext_reseller_cust_id": "Reseller_cust_id"
}
Standard Feature Set (fs2)
The following is an example using the standard feature set.
POST Request
URL: https://api.syniverse.com/numberidentity/v3/lookup
Request headers
content-type: application/json
ext_trx_id=Testqa
ext_reseller_cust_id=Reseller_cust_id
authorization= Bearer xxxxxxxxxxxxxxxxxxxxx
Payload
{"phone_number":"+1XXXXXXXX70","feature":"fs2"}
Response (for POST)
{
"numberidentity":{
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id": "4455",
"carrier_name": "BANDWIDTH.COM CLEC LLC",
"number_type": "L",
"country_iso_code": "USA",
"country": "United States"
},
"tracking_id": "101580180391472739483159",
"ext_trx_id": "Testqa",
"ext_reseller_cust_id": "Reseller_cust_id"
}
Legacy Feature Set (fs23)
The following is an example using the Legacy feature set. This feature set is similar to standard but does not include country_iso_code and does include porting_status, carrier_mcc, carrier_mnc, nisds and deactivation detail such as carrier_id, carrier_name and deactivation_date.
POST Request
>URL: https://api.syniverse.com/numberidentity/v3/lookup
Request headers
content-type: application/json
ext_trx_id=Testqa
ext_reseller_cust_id=Reseller_cust_id
authorization= Bearer xxxxxxxxxxxxxxxxxxxxx
>Payload
{"phone_number":"+1XXXXXXXX70","feature":"fs23"}
Response (for POST)
{ </p> <p>"numberidentity": { </p> <p>"number": "+18316274789", </p> <p>"validity": "true", </p> <p>"carrier_id": "15920", </p> <p>"carrier_name": "AT&T - PSTN", </p> <p>"number_type": "L", </p> <p><"country": "United States", </p> <p>"porting_status": "false", </p> <p>"carrier_mcc": "", </p> <p>"carrier_mnc": "", </p> <p>"nisds": "mnp", </p> <p>"deactivation_detail": { </p> <p>"carrier_id": "", </p> <p>"carrier_name": "", </p> <p>"deactivation_date": "" </p> <p>}, </p> <p>"deactivation_date": "", </p> <p>"tracking_id": "2111020131701560423852203" </p> <p>}, </p> <p>"ext_trx_id": "1234", </p> <p>"ext_reseller_cust_id": "56789" </p> <p>} </p> <p><code>
Premium Disconnect Feature Set (fs5)
The following is an example using the Premium Disconnect feature set. This feature set is similar to Premium Deactivation but provides the derived disconnect data instead of raw de-activation data.
POST Request
>URL: https://api.syniverse.com/numberidentity/v3/lookup
Request headers
content-type: application/json
ext_trx_id=Testqa
ext_reseller_cust_id=Reseller_cust_id
authorization= Bearer xxxxxxxxxxxxxxxxxxxxx
>Payload
{"phone_number":"+1XXXXXXXX70","feature":"fs5"}
Response(for POST)
Following sample responses illustrate three possible outcomes: Case 1, Case 2 and Case 3.
Case 1
Outcome for a recently ported number.
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id":"1234",
"carrier_name": "SPRINT PCS",
"country_iso_code": "USA",
"country": "United States",
"number_type": "M",
"carrier_mcc": "123",
"carrier_mnc": "214",
"last_known_event": "None"
},
"tracking_id": "101580180391472739483159",
"ext_trx_id": "Testqa",
"ext_reseller_cust_id": "Reseller_cust_id"
}
Outcome for recently deactivated but not ported number.
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id": "1125",
"carrier_name": "VERIZON WIRELESS",
"number_type": "M",
"country_iso_code": "USA",
"country": "United States",
"carrier_mcc": "310",
"carrier_mnc": "012",
"account_type": "",
"last_known_event": "Disconnect",
"disconnect_date": "2018-08-10T00:00Z"
},
"ext_trx_id": "1234567890123456",
"tracking_id": "211010189721534845085726"
}
Case 3
Outcome for a number without any deactivation or porting history
{
"numberidentity": {
"number": "+1XXXXXXXX70",
"validity": "true",
"carrier_id":"1234",
"carrier_name": "SPRINT PCS",
"country_iso_code": "USA",
"country": "United States",
"number_type": "M",
"carrier_mcc": "123",
"carrier_mnc": "214",
"account_type":"Prepaid",
"last_known_event": "None"
},
"tracking_id": "101580180391472739483159",
"ext_trx_id": "Testqa",
"ext_reseller_cust_id": "Reseller_cust_id"
}
Batch Processing
While performing a single number lookup is valuable, there may be times when you have a set or group of numbers you need to process. Batch processing makes this an easier task. With batch processing you can send a file that contains multiple phone numbers and the system performs a lookup for each number within the file as a batch process.
Before you can start you need:
Input and Output Files
Description |
|
|
Input File Extension |
Can be any extension. Examples: .csv or .txt |
|
Input File Naming Convention |
No specific naming convention is required For example: partner_scrub_20190325_091011.txt |
|
Input File Content Format |
Phone Number’s must be in E.164 format. Scrub, Unsubscribe and Monitor Examples: +183XXXXX916 Combined Scrub & Monitor Example: +183XXXXX916,, Additional optional fields can also be used to specify the phone number opt-in date and a customer reference |
|
Output File Type |
Compressed Comma Separated Values File |
|
Output File Summary Report |
Not Applicable |
|
Output File |
<OutputFileNamingExpression>.gz For example: partner_scrub_20190325_091011.txt.gz |
|
Output File Content Format |
Scrub: fs1: number,validity,carrier_id,carrier_name,number_type,country_iso_code,country, fs2: number,validity,carrier_id,carrier_name,number_type,country_iso_code,country, fs23: number,validity,carrier_id,carrier_name,number_type,country,porting_status, fs5: number,validity,carrier_id,carrier_name,number_type,country_iso_code,country, Scrub & Monitor: fs1: Number,Validity,Carrier Id,Carrier Name,Number Type,Country ISO Code,Country,MCC,MNC,Account Type,Last Known Event,Porting Date,Previous Carrier Id,Previous Carrier Name,Deactivate Date,External Tracking Id,External Reseller Customer Id,Tracking Id,Monitored,Unique ID fs5: number,validity,carrier_id,carrier_name,number_type,country_iso_code,country,carrier_mcc,carrier_mnc,last_known_event, previous_carrier_id,previous_carrier_name, disconnect_date,ext_trx_id,ext_reseller_cust_id,tracking_id,Monitored,Unique ID Note: The content formats shown above are also examples of the header that displays in the batch output file when a header is requested. |
|
Output Error File Format |
<sl_no>|<phone_number>|<error_description> Example 5|+170XXXXX118|PROCESSING_ERROR - Canadian Number, Further authorization is required |
|
Retry File Format |
Phone Number’s must be in E.164 format. Examples: +183XXXXX916 Note: This should be same as Input file format (only MDNs that need to be retried, should be part of retry file.) |
Note: For Canada PNV, you are required to be whitelisted by the country’s authorities to receive PNV attributes for Canadian phone numbers. If no whitelisting is present, the default response from the PNV platform is to error with the reason “Canadian Number – further authorization is required”.
Batch Request
For batch requests, there are four Batch Scrub and two Batch Scrub & Monitor file layouts, each specific to the desired feature set:
- NIS-Scrub-v3-fs1
- NIS-Scrub-v3-fs2
- NIS-Scrub-v3-fs23
- NIS-Scrub-v3-fs5
- NIS-Scrub-Monitor-fs1-v1
- NIS-Scrub-Monitor-fs5-v1
The batch output can include a header and this is specified in the payload using the attribute “outputFileHeaderType”. For this attribute, if you include the value “basic”, the output includes a header. If you do not include the attribute or provide no value for the attribute, the output does not include the header.
Sample Output with Header
The following screens provide an example of the output with a header.
Feature Set 1 (fs1)
Feature Set 2 (fs2)
Feature Set 23 (fs23)
POST Request
URL: https://api-int.syniverse.com/aba/v1/schedules
Request with Header
content-type: application/json
int-companyId: 1234<br> ext_trx_id=trx_id
ext_reseller_cust_id=Reseller_cust_id
authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Payload
{
"schedule": {
"jobId": "NIS-Scrub-v3-fs23",
"name": "NIS Scrub",
"inputFileId": "c9ba424a-e007-4239-9f69-2a57666f199b",
"fileRetentionDays": 3,
"scheduleRetentionDays": 3,
"outputFileNamingExpression": "NIS-Scrub-fs23-Header.txt",
"outputFileFolder": "ScrubAA",
"outputFileHeaderType": "basic",
"outputFileTag": "AA Tag",
"jobRuntimeContext": {}
}
}
Note: For traceability, ext_trx_id and ext_reseller_cust_id (supplied as part of request header when scheduling a job) is provided on each record in the batch success output file.
Event Monitoring
You can proactively monitor a set of phone numbers and receive alerts when the number experiences a change. This ability is available by adding the Event Manger service to Phone Number Verification. Event Manager is available for all users and companies in the Syniverse Developer Community and its purpose is to send alerts from a Syniverse solution back to your environment.
For Phone Number Verification, the monitoring service can alert you to the following changes:
- Deactivation Status
- True Disconnects
To get started, you need to establish your delivery configurations – used to send real-time events – then schedule when you want to receive delivery and finally, subscribe to receive notifications.
Establish Delivery Configurations
Callback URL Setup
Follow below steps to configure the callback URL.
- From the Syniverse Developer Community portal, select the Event Manager | Delivery Configurations. The Delivery Configurations details & administration screen displays.
- Click New Delivery Configuration. The Create Delivery Configuration screen displays.
- Enter the Delivery Configuration Name. This field is required.
- For Is Scheduled, select No.
- For the Address enter your service URL (this should be ready to accept event notifications). The address is required and must follow this format: http://subdomain.domain.top-level-domain
For example: http://event.test.com - For the Delivery Protocol , select REST. This field is required.
- For Throttling, leave this value empty for now – more instructions for entering this value are included later in this document.
- For Delivery Format , select JSON.
- Set Is Active to Yes.
- Click Create.
You've now created a delivery configuration which can be used to send real-time events to a defined endpoint.
Schedule Delivery of Event Notifications
Follow below steps to schedule delivery of event notifications
- From the Syniverse Developer Community portal, select the Event Manager | Delivery Configurations. The Delivery Configurations details & administration screen displays.
- Click New Delivery Configuration. The Create Delivery Configuration screen displays.
- Enter the Delivery Configuration Name . This field is required.
- For Is Scheduled , select Yes.
- Setup the desired schedule. You can use Simple Schedule or enter the schedule.
-
- To Use simple schedule:
- Click the toggle to Yes.
- For Schedule to select from the Every drop-down. Choose from: Minute, Hour, Day, Week, Month or Year.
- To Configure a schedule:
- To Use simple schedule:
-
-
- Set the toggle to No.
- Enter the Cron expression .
-
- If you want Latest event delivery only , click the toggle to Yes. If not, leave as No.
- For Delivery Format , select JSON.
- Set Is Active to Yes.
- Click Create.
Notification Subscription Configuration
To configure and subscribe to notifications, follow these steps:
- From the Syniverse Developer Community portal, select the Event Manager | Subscriptions. The Subscriptions details & administration screen displays.
- Click New Subscription. The New Topic Subscription screen displays.
- For the Topic, select MSS-Messages from the drop-down. This field is required.
- For Event Type select All Types from the drop-down.
- Select the Delivery Configuration from the drop-down. This is the schedule set up in the earlier step Schedule Delivery of Event Notifications.
- For Matching Criteria, leave this field empty.
- Select the Start Date. Ensure the start date and time do not occur in the future. Time is represented in UTC, which is +5 hours Eastern Standard Time (EST).
- Leave End Date and Time empty.
- Click Create.
Batch Subscription
Follow these steps to subscribe to state changes to a list of phone numbers.
1.Create File Repository
Create a file repository for your application and obtain your unique file repository identifier by posting a "HTTP POST Request" to the following URL - https://api.syniverse.com/mediastorage/v1/files.
Example Request and Response
HTTP Request Header
|
|
HTTP Request Body
|
|
||
|
|
||
HTTP Response Body
|
|
2.Upload Batch Scrub File
Upload the batch file, containing phone numbers to be monitored, to the URL obtained from the above response – the file_uri attribute value of the response contains the URL.
For the above example, the URL would be https://api.syniverse.com/mediastorage/v1/files/39....
Typical HTTP header values of a sample request are included below:
HTTP Request Header
|
|
Each line of the batch file should contain MDN followed by 2 commas. An example is provided below -
Batch Scrub File
|
|
3.Schedule Scrub Notifications
To create a schedule for receiving notifications, post a request to https://api.syniverse.com/aba/v1/schedules.
Sample requests and responses are included below:
HTTP Request Body
|
|
HTTP Response Header
|
|
HTTP Response Text
|
|
4.Monitoring Notifications
Monitoring notifications are delivered (in the format below) to the configured notification URL.
{
"topic":"MSS-Messages","attempt":1,"event":{"fld-val-list":{"app_name":"ESS","company-id":110400,"modified_time":"2019-02-15T08:05:07Z","file_uri":"https://api.syniverse.com/mediastorage/v1/files/04099d54-ca28-48f7-af89-24a814823fc1/content","file_status":"COMPLETE","file_id":"04099d54-ca28-48f7-af89-24a814823fc1","file_tags":"ESS","expire_time":"2019-02-22T08:05:05Z","file_size":19867},"evt-tp":"event_file_download","timestamp":"2019-02-20T05:16:06.361Z"},"event-id":"MOHmryRKTSqXr7InTXxWsw"
}
The file URL - https://api.syniverse.com/mediastorage/v1/files/04... contains the actual notification events; for example:
{
"topic":"NIS-Events","attempt":1,"event":{"fld-val-list":{"number":"+19728787429","previous_carrier_id":"16291","previous_carrier_name":"T-MOBILEUSAINC.","tracking_id":"1971475107","deactivation_date":"2019-02-12T00:00:00Z"},"evt-tp":"deactivation_event","timestamp":"2019-02-15T07:45:21.358Z"},"event-id":"m_bWQp9hSzuSKnvUeQNPZg"
}
{
"topic":"NIS-Events","attempt":1,"event":{"fld-val-list":{"number":"+19728774275","previous_carrier_id":"16041","previous_carrier_name":"SPRINTSPECTRUML.P.","tracking_id":"1991866799","deactivation_date":"2019-02-12T00:00:00Z"},"evt-tp":"deactivation_event","timestamp":"2019-02-15T07:45:21.45Z"},"event-id":"b2Ze_hA0QrS2TRLH8e1JcA"
}
{
"topic":"NIS-Events","attempt":1,"event":{"fld-val-list":{"number":"+19728789010","previous_carrier_id":"16291","previous_carrier_name":"T-MOBILEUSAINC.","tracking_id":"1967819992","deactivation_date":"2019-02-12T00:00:00Z"},"evt-tp":"deactivation_event","timestamp":"2019-02-15T07:45:21.381Z"},"event-id":"AvRoRNHPTEuod5okI9C3_Q"
}
About Syniverse
Syniverse is the world’s most connected company—we pioneer innovations that take businesses further. Our secure, global network reaches billions of people and devices. Our engagement platform powers the customized experiences of the future. And the millions of secure transactions we drive every minute are revolutionizing how goods and services are exchanged. We have always led companies to reimagine the boundaries of possibility. Today we’re delivering on opportunities with the power to change the world. www.syniverse.com