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:

    1. Go to the Service Offerings tab.
    2. Click Phone Number Verification Service. The details and pricing page displays.
    3. Click the arrow to expand Subscriptions.
    4. Click Subscribe … and a pop-up displays.
    5. Select your Account from the drop-down.
    6. Click Confirm.
  • An Application with enabled APIs – To enable the APIs, you create a new application or edit an existing one.
    1. Click Create New or click on the application name to edit an existing application.
    2. Click on the button to toggle SDC Gateway Services and Phone Number Verification Service to ON.
    3. 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
+183XXXXX917
+183XXXXX918
+183XXXXX919

Combined Scrub & Monitor Example:

+183XXXXX916,,
+183XXXXX917,20170515-010101 Z,
+183XXXXX918,20170515-010101 Z,TestRef123
+183XXXXX919,,

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,
carrier_mcc,carrier_mnc,account_type,last_known_event,porting_date,
previous_carrier_id,previous_carrier_name,deactivation_date,ext_trx_id,
ext_reseller_cust_id,tracking_id

fs2:

number,validity,carrier_id,carrier_name,number_type,country_iso_code,country,
carrier_mcc,carrier_mnc,ext_trx_id,ext_reseller_cust_id,tracking_id

fs23:

number,validity,carrier_id,carrier_name,number_type,country,porting_status,
carrier_mcc,carrier_mnc,ext_trx_id,ext_reseller_cust_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

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
+183XXXXX917
+183XXXXX918
+183XXXXX919

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.

  1. From the Syniverse Developer Community portal, select the Event Manager | Delivery Configurations. The Delivery Configurations details & administration screen displays.
  2. Click New Delivery Configuration. The Create Delivery Configuration screen displays.
  3. Enter the Delivery Configuration Name. This field is required.
  4. For Is Scheduled, select No.
  5. 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
  6. For the Delivery Protocol , select REST. This field is required.
  7. For Throttling, leave this value empty for now – more instructions for entering this value are included later in this document.
  8. For Delivery Format , select JSON.
  9. Set Is Active to Yes.
  10. 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

  1. From the Syniverse Developer Community portal, select the Event Manager | Delivery Configurations. The Delivery Configurations details & administration screen displays.
  2. Click New Delivery Configuration. The Create Delivery Configuration screen displays.
  3. Enter the Delivery Configuration Name . This field is required.
  4. For Is Scheduled , select Yes.
  5. 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:
      • Set the toggle to No.
      • Enter the Cron expression .
  1. If you want Latest event delivery only , click the toggle to Yes. If not, leave as No.
  2. For Delivery Format , select JSON.
  3. Set Is Active to Yes.
  4. Click Create.

Notification Subscription Configuration

To configure and subscribe to notifications, follow these steps:

  1. From the Syniverse Developer Community portal, select the Event Manager | Subscriptions. The Subscriptions details & administration screen displays.
  2. Click New Subscription. The New Topic Subscription screen displays.
  3. For the Topic, select MSS-Messages from the drop-down. This field is required.
  4. For Event Type select All Types from the drop-down.
  5. Select the Delivery Configuration from the drop-down. This is the schedule set up in the earlier step Schedule Delivery of Event Notifications.
  6. For Matching Criteria, leave this field empty.
  7. 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).
  8. Leave End Date and Time empty.
  9. 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

Content-Type: application/json

Authorization: Bearer 3a157b7c71e49ad5b69365e8ee8daac5

int-companyid: 829

int-applicationId: 528

Host: lab-api-int.syniverse.com

Content-Length: 186

HTTP Request Body

 

{

"file_name": "US_MDN_7",

"file_tag": "testtag",

"file_folder": "/files",

"app_name": "ABA",

"expire_time": "",

"checksum": "",

"file_fullsize": "4096",

"compressionType": ""

}

{

"file_name": "ABA_SCRUB_TEST_QA",

"file_tag": "dalscrub",

"file_folder": "/files",

"app_name": "ABA",

"expire_time": "",

"checksum": "",

"file_fullsize": "4096",

"compressionType": ""

}

 

 
     

HTTP Response Body

{"file_id":"3999d730-c084-4084-a9e8-eac5be04a24a", "file_name":"US_MDN_7", "company-id":"821",

"file_folder":"/files", "app_name":"ABA","file_status":"CREATED",

"file_uri":"https://api.syniverse.com/mediastorage/v1/files/3999d730-c084-4084-a9e8-eac5be04a24a/content",

"file_version":1, "file_checksum":0, "file_size":0,"file_fullsize":4096, "creation_time":"2017-05-08T11:09:12.403+0000",

"modified_time":"2017-05-08T11:09:12.403+0000","file_retention_time":30,"expire_time":"2017-06-07T11:09:12.403+0000"}

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

 

Content-Type: application/octet-stream

Authorization: Bearer 3a157b7c71e49ad5b69365e8ee8daac5

int-companyid: 829

int-applicationId: 528

Host: lab-api-int.syniverse.com

Each line of the batch file should contain MDN followed by 2 commas. An example is provided below -

Batch Scrub File

+12345678901,,

+12345678902,,

+12345678903,,

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

 

{

"schedule": {

"jobId": "NIS-Monitor-v2",

"name": "Subscribe",

"inputFileId": "753ca4cb-f02b-492c-a27a-185a12099ec0",

"outputFileNamingExpression": "Complete_file.txt",

"outputFileFolder": "Phone_Number_Verification_Folder",

"outputFileTag": "Phone_Number_Verification_Sample_File_Complete_Tag",

"fileRetentionDays": 30,

"scheduleRetentionDays": 30,

"jobRuntimeContext": {

"subscribeevents": "all",

"subscribedestinationid": "1711"

}

}

}

HTTP Response Header

 

HTTP/1.1

201Created

Server: openresty/1.11.2.1

Date: Mon, 08May 201711:50:48GMT

Content-Type: application/json

Connection: keep-alive

int-companyid: 829

Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type

Access-Control-Allow-Origin: *

ext_trx_id: 5162cfe6-82af-4a4b-aa18-310e7eea671e

int-appId: 1025

Location: https://10.168.4.18:8245//aba/v1/schedules/979e69e...

int-txnid: sx1uQ9aPFEDb64OYBrJoMIxzueeofPyK

int_trx_id: sx1uQ9aPFEDb64OYBrJoMIxzueeofPyK

Access-Control-Allow-Origin: *

Access-Control-Allow-Headers: Content-Type, user-token

Access-Control-Expose-Headers: user-token

Access-Control-Allow-Origin: *

Access-Control-Allow-Headers: Content-Type, user-token

Access-Control-Expose-Headers: user-token

Content-Length: 323

HTTP Response Text

{"schedule":{"id":"979e69e6-bb7e-49f2-a64b-63749482b5c1", "jobId":"NIS-Monitor-v2",

"name":"NISTestScrub", "inputFileId":"753ca4cb-f02b-492c-a27a-185a12099ec0", "fileRetentionDays":2,

"scheduleRetentionDays":2, "outputFileNamingExpression":"Complete_file.txt",

"outputFileFolder":"Phone_Number_Verification_Folder",

"outputFileTag":"Phone_Number_Verification_Sample_File_Complete_Tag",

"jobRuntimeContext":{"subscribeevents": "all", "subscribedestinationid": "1711"}}}

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