Phone Number Verification User Guide

This page contains the Quick Startup and User Guide for the Phone Number Verification Service

Prerequisites

Before starting with the Phone Number Verification, the following items needs to be configured and in place:

Create Company Environment in the Syniverse Developer Community
Subscribe to Phone Number Verification
Subscribe for an OPTIONAL Service Offering to Media Storage Service (if doing batch look-ups or monitoring)
Subscribe for an OPTIONAL Service Offering to API Batch Automation (if doing batch look-ups or monitoring)
Application created Syniverse Developer Community
Application resources have Phone Number Verification, Media Storage Service (MSS) and API Batch Automation turned ON

Syniverse Phone Number Verification Service can be used in multiple ways. When only doing single number look-ups there is a dependency to the Syniverse Developer Community.

When doing batch look-ups and/or monitoring then following services need to be configured as well:

Media Storage Service - Manage the upload and download of the file to be used for batch jobs
API Batch Automation - Manage job automation based on the details in the file
Event Manager - Receive events based on the numbers being monitored

Quick Start Overview

This guide contains the Quick Start Guide on how to do a single number lookup. Requirement is that you already have a Company environment and Application created into the Syniverse Developer Community.

You can run a first test with the Phone Number Verification API. This allows you to get the knowledge of what data is going to be available to you from a number.

We recommend using cURL or an application like Postman to test your calls.

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR ACCESS TOKEN}" "https://api.syniverse.com/numberidentity/v3/numbers/%2B{PHONENUMBER}"

This should give you the following response:

{
  "numberidentity": {
    "number": "+[PHONENUMBER]",
    "validity": "",
    "carrier_id": "",
    "carrier_name": "[MNO Name]",
    "country": "",
    "carrier_mcc": "",
    "carrier_mnc": "",
    "number_type": "",
    "account_type": "",
    "country_iso_code": "",
    "porting_date": "",
    "previous_carrier_id": "",
    "previous_carrier_name": "",
    "last_known_event": ""
  },
  "tracking_id": "[Unique Tracking ID]"
}

You can also query different data sets from the environment by using the following API calls

Feature Set 1 which is Premium data feed and only available in US and Canada

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR ACCESS TOKEN}" "https://api.syniverse.com/numberidentity/v3/numbers/%2B{PHONENUMBER}?feature=fs1"

Feature Set 2 which is Standard data feed available Globally

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR ACCESS TOKEN}" "https://api.syniverse.com/numberidentity/v3/numbers/%2B{PHONENUMBER}?feature=fs2"

In addition to the feature set 1 and 2, additional feature set might be defined. In such cases the identifier for the newly created feature set needs to be specified in the query parameters of the lookup.

Note :Cross reference to appropriate documentation to reach out to Implementation team for provisioning of this new feature set.

User Guide

This user guide contains more detailed information to setup the Batch lookup and/or Monitoring for Phone Number Verification services.

Batch Lookup

Doing a Batch lookup is where a file is uploaded to Syniverse Media Storage Service, which contains multiple phone numbers in a txt file. This file is then read by API Batch Automation and it runs scheduled job. This job calls Phone Number Verification API on behalf of the Customer and creates a response file, which is then stored to the Media Storage Service for Customer to download.

The requirement for this step is that Customer has already the necessary Service Offering subscriptions in place. This requires: Media Storage Service, API Batch Automation and Phone Number Verification

Configure Event Manager

Event Manager is used to send information about when a file is ready for download and it also sends status about the Batch Automation job.

Hover over the Event Manager on the top menu
Select “Delivery Configurations”
Click "New Delivery Configuration"
Give the delivery configuration a name
Enter the Address (a URL where the events are sent to)
Delivery protocol has to be REST
Set throttling (how many events are sent per minute to the endpoint), This can be empty
Select delivery format either (JSON or XML)
Turn configuration Active
Click "Create"

This has now created a delivery configuration, which sends the events to your environment about the file processing

If your environment needs authentication before event delivery, please refer to the Event Manager User Guide

Create Topic Subscription which is needed to manage all the specific events that are needed to automate the processes

Hover over the Event Manager
Select Subscriptions
Click "New Subscription"
Select Topic: MSS-Messages
Event Type:
1. All Types – All Media Storage Service Events
2. event_file_complete – Informs when a file has been completed and ready for download
3. event_file_delete – Sends an event when the file has been deleted
4. event_file_download – Sends an event when a file download has been completed
Select Delivery Configuration
Set matching criteria OPTIONAL
Select Start Date (This is the date when the subscription turns active)
Enter End Date (Date when the subscription stops sending events)
Click "Create"

You now have a valid Event Manager setup that sends notifications to the delivery configuration created, based on Media Storage Service events.

If you want to receive the Batch Automation events as well, repeat previous steps but Select Topic: ABA-Messages.

Upload the File into Media Storage Service

Once the Event Manager has been configured and you have all the subscriptions for Service Offerings in place, it is time to upload the file.

This process has two steps to upload the file: (For more details on the needed API calls, please refer to the Media Storage Service Examples page)

File Context Creation - This creates the File Context with details about the content which is going to be uploaded
File Content Upload - This step uploads the content to the File Context

Start a Scheduled Job through Batch Automation

Once the file has been uploaded and the file status is "Complete", this means that Batch Automation is can now start reading the file and start running the scheduled job. Please check the Batch Automation User Guide on how to run the specific job for Phone Number Verification Scrub.

Batch Automation takes the file, parses the content of the file and runs the job. It also gathers the responses to three new files, which are provided back to the Customer through Media Storage Service. The three file types are:

Output File - This contains all successfully run numbers. The output file is compressed using GZIP in order to reduce the filke size. This is done due to the large size of the output file.
Retry File - This contains all the numbers which were correctly formatted but there was a timeout in the system
Error File - This contains all the numbers which were improperly formatted, were not valid numbers and also information about the retry file numbers.

Customer can download the Retry and Error files for further analysis, but also the retry file can be scheduled for a new run be recreating the Batch Automation steps.

Running a Monitoring Job

Running a Monitoring Job is very similar to the previous step in running the Batch Lookup. The difference is that Monitoring job takes the file and subscribes each number for Monitoring into the Event Manager.

This means that in Event Manager there needs to be a valid delivery configuration in place, and to do that please refer to Event Manager User Guide

These events can be delivered to the End Customer either as soon as there is information available or store that information to a file for scheduled delivery. The Scheduled Delivery option stores the events into a file for download through Media Storage Service. This schedule can be set to be daily, weekly or monthly.

Steps to repeat for running a Monitoring Job:

Create Delivery Configuration specifically for Monitoring events
Upload a file into a system containing numbers you are interested to monitor
Start a Batch Automation job for Monitoring