NIS 3.0 API documentation

Phone Verification API documentation version 5.0.0

https://api.syniverse.com/numberidentity/v3

About Phone Verification

The purpose of this specification is to describe the Syniverse Phone Number Verification capabilities, core concepts, and API set. The Phone Number Verification (PNV) offers a rich suite of RESTful APIs that allow lookup of salient phone number data, batch lookup of number data, scheduling of number lookup and proactive monitoring of numbers of interest for changes to critical attributes. Number lookup returns salient attributes of a phone number e.g., validity, country, carrier, porting status, and deactivation details).

The query parameters includes the feature set selection for the number lookup. The feature set is the collection of attributes.

numberidentity

Number Identity resource.

Resource attributes:

number (string): Phone number in E.164 format e.g., +12125551212 . The max length of this attribute is 20
validity (boolean): Validity of phone number . This attribute indicates if the number is part of a valid line range of phone numbers . Allowed values - true,false
carrier_id (string): Identifier of carrier serving the phone number’. The list of all carrier ids is available in the Phone Number Verification Annexure. The max length of this attribute is 15.
carrier_name (string): Name of carrier serving the phone number. The max length of this attribute is 256.
number_type : (string): Type of phone number supported :
- M (mobile)
- L (Landline),
- VM (VOIP Mobile)
- VL (VOIP Landline)

Note : Empty value if number is not valid or if the number_type is not known. The max length supported is 2.

country_iso_code (string): The 3 letter ISO code of the country
country (string): Name of the country the phone number belongs to. The max length of this attribute is 256.
carrier_mcc(string): Mobile Country Code of carrier most recently serving the phone number. The max length supported is 3. Empty value if the number is not valid.

carrier_mnc string): Mobile Network Code of carrier most recently serving the phone number. The max length of this attribute is 3. Empty value if the number is not valid.
porting_status (boolean): Indicates that the Phone Number has been Ported during its life time. Allowed values - true,false
account_type (string): Type of Account for the ported phone number. Allowed values are Prepaid, Postpaid or empty. The max length of this attribute is 15. This attribute applies only when the phone number is valid mobile and ported. In all other cases empty values is returned.
last_known_event
- (string): Most recent activity on the phone number. Allowed values are
- None – No activity reported on this number.
- Ported - Number has been ported to the carrier identified by carrier_id on porting_date
- Deactivated – Number was deactivated from the carrier identified by previous_carrier_id on deactivation_date.

Note : The number may be deactivated either for porting OR for true disconnect. Since porting information is available near real-time, the last known event “deactivated” is most likely a true disconnect where a number is returned to the recycling pool.

porting_date (date): Indicates the date on which the phone number was ported. Sample value '23-03-2014 T10-12-23Z'. The max length supported is 20. This attribute applies only when “last_known_event” is ported.
previous_carrier_id (string): Identifier for the carrier previously serving the phone number. The max length of this attribute is 15. This attribute applies only when “last_known_event” is either ported or deactivated
previous_carrier_name (string): Name of the carrier previously serving the phone number. The max length allowed is 256. This attribute applies only when “last_known_event” is either ported or deactivated.
deactivation_date (date): Date when phone number was deactivated. Sample value '23-03-2014 T10-12-23Z'. The max length of this attribute is 20. This attribute applies only when “last_known_event” is deactivated.
ext_trx_id (string): This is the unique identifier sent by customer in request header to track the request/response chain for the API call. The value of this attribute will be extracted from the header of the GET request.This header is Optional.
ext_reseller_cust_id (string): This attribute represents the customer of our customer using the Phone Verification service. The max length of this attribute is 64. The value of this attribute will be extracted from the header of the GET request. This header is Optional.
tracking_id (string): PNV generated unique identifier to track the request response chain. The max length of this attribute is 38. This can be used for troubleshooting or tracking the requests from the customer.

/numbers/{number} get

get

Returns available information on the phone number.

Request
Response

URI Parameters

number: required (string)
This is the unique identifier of the number resource.

Query Parameters

feature: (string)
Parameter

HTTP status code 200

Successful operation

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "numberidentity",
  "type": "object",
  "properties": {
    "number": {
      "type": "string"
    },
    "validity": {
      "type": "boolean"
    },
    "carrier_id": {
      "type": "string"
    },
    "carrier_name": {
      "type": "string"
    },
    "number_type": {
      "type": "string"
    },
    "country_iso_code": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "carrier_mcc": {
      "type": "string"
    },
    "carrier_mnc": {
      "type": "string"
    },
    "account_type": {
      "type": "string"
    },
    "last_known_event": {
      "type": "string"
    },
    "porting_date": {
      "type": "date"
    },
    "previous_carrier_id": {
      "type": "string"
    },
    "previous_carrier_name": {
      "type": "string"
    },
    "deactivation_date": {
      "type": "date"
    },
    "ext_trx_id": {
      "type": "string"
    },
    "ext_reseller_cust_id": {
      "type": "string"
    },
    "tracking_id": {
      "type": "string"
    }
  }
}

HTTP status code 400

Bad Request. The request could not be understood by the server.

Possible Error Codes:

NIS04000001 - Invalid Phone format - Number format should be in E.164 format and URL encoded. Ex : %2B12125551212. Please re-submit request with correct format.
NIS04000002 - Invalid Feature - Feature values must be fs1 or not provided
NIS04000003 - Invalid parameter - Invalid parameters provided. Please check the documentation for valid values.
NIS04000004 - Invalid Version - Unsupported Version. Please check the documentation for valid versions.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 401

Unauthorized. The request requires user authentication.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 402

Payment Required.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 403

Forbidden. The user does not have permission to access the specified resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 404

"Not Found. The server has not found anything matching the Request-URI."

HTTP status code 409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 412

Precondition Failed. The server does not meet one of the preconditions that the requester put on the request.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 429

Too Many Requests. The user has sent too many requests in a given amount of time.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 500

Server Error. An error has been encountered while processing this request.

Possible Error Codes:

NIS05000001 - Internal Server Error - Service is temporarily unavailable. Please retry later

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 503

Server Unavailable.

Phone Number Monitoring Service:

PNV Service collects information on telephone numbers from multiple sources which may be of business interest to customers for realization of their business functions. Following sections enumerates the events

Event Name	Business Context	Potential Use
deactivation_event	The Deactivation event is created whenever a number is deactivated, whether permanently or for the purpose of porting. The same number can be visible either in porting_event or truedisconnect_event: If the deactivation event of a phone number is followed by a porting event or not.	Customers interested in scrubbing their marketing databases may wish to subscribe to the deactivation event for indication of activity on the phone number.
porting_event	The Porting change event is created when a number is ported from one carrier family to another and the porting is considered a competitive port. This number is also expected to show up in the deactivation_event if the same number is subscribed to the monitoring service.	Customers who route messages directly to service providers may update their subscriber databases upon receipt of such events.
truedisconnect_event	This event provides a reliable method for tracking deactivation of numbers as it is triggered after reasonable provision for porting. A true disconnect constitutes a deactivation event that is NOT related to a porting event. A true disconnect represents the phone numbers that are being recycled by carriers and are open to be assigned to another individual.	Customers looking to ensure that their communication only reaches opted-in consumers in their database, should remove phone numbers that occurred a truedisconnect from their calling list.

Business Events

deactivation_event:

Attribute	Data Type	Mandatory	Description
number	String	yes	Phone number in E.164 format
previous_carrier_id	String	no	Identifier of the carrier previously serving the phone number. (see NIS Annexure)
previous_carrier_name	String	no	Name of the carrier serving the phone number (see NIS Annexure)
deactivation_date	date	yes	Name of the carrier serving the phone number (see NIS Annexure)
tracking_id	String	no	Unique Id generated by NIS for tracking the event

porting_event:

Attribute	Data Type	Mandatory	Description
number	String	yes	Phone number in E.164 format
carrier_id	String	no	Identifier of the carrier serving the phone number (see NIS Annexure)
carrier_name	String	no	Name of the carrier serving the phone number (see NIS Annexure)
previous_carrier_id	String	no	Identifier of the carrier previously serving the phone number. (see NIS Annexure)
previous_carrier_name	String	no	Name of the carrier serving the phone number (see NIS Annexure)
porting_date	dateTime	yes	Date of porting of number in format: "YYYY-MM-DDTHH:MM:SSZ". ex. 2016-01-02T12:23:56Z
tracking_id	String	no	Unique Id generated by NIS for tracking the event

truedisconnect_event:

Attribute	Data Type	Mandatory	Description
number	String	yes	Phone number in E.164 format
previous_carrier_id	String	no	Identifier of the carrier previously serving the phone number. (see NIS Annexure)
previous_carrier_name	String	no	Name of the carrier serving the phone number (see NIS Annexure)
deactivation_date	date	yes	Name of the carrier serving the phone number (see NIS Annexure)
tracking_id	String	no	Unique Id generated by NIS for tracking the event

Appendix A : Phone Verification Service – Lookup Attributes

Name	Description	Type	Size	Example	Default Value
feature	Requested Feature set			"fs1"	"fs1"
number	Phone Number in E.164 Format	String	20	“+12125551212"
validity	Indicates if the number is part of valid line range.	boolean		TRUE
carrier_id	Identifier of the carrier serving the phone number	String	15	"16291"
carrier_name	Name of the carrier serving the phone number	String	256	"T-MOBILE USA INC"
number_type	Type of Phone Number Supported	String	2	"M"
country_iso_code	The 3 letter ISO code of the country	String	3	"USA"
country	The name of the country the phone number belongs to	String	256	"United States
carrier_mcc	Mobile Network code of the carrier most recently serving the phone number.	String	3	"310"	Empty value if the number is not valid
carrier_mnc	Mobile Network Code of carrier most recently serving the phone number.	String	3	"160"	Empty value if the number is not valid
account_type	Type of Account for Valid Ported Mobile Phone number	String	15	"Prepaid"	Empty value if number is not ported valid usa/cn mobile number. International number account type is empty.
porting_status	Phone Number has been Ported atleast once during its life time	boolean		true
last_known_event	Most recent activity on the Phone Number.	String		"Ported"
porting_date	Indicates the date on which the phone number was ported.	date	20	2014-11-15T00:00Z	Applies ONLY if last_known_event is PORTED.
previous_carrier_id	Identifier of the carrier previously serving the phone number.	String	15	"16291"	Applies ONLY if last_known_event is Ported or Deactivated. International ( india) comes as EMPTY values.
previous_carrier_name	Name of the carrier previously serving the phone number.	String	256	"T-MOBILE USA INC."	Applies ONLY if last_known_event is Ported or Deactivated. International ( india) comes as EMPTY values
deactivation_date	Date when phone number was deactivated.	date	20	"2010-02-07T00:00Z"	Applies ONLY if last_known_event is Deactivated.

Appendix B : Phone Verification Service – International Coverage

Name	Description	Coverage
feature	Requested Feature set
number	Phone Number in E.164 Format	US/CA/IN/International
validity	Indicates if the number is part of valid line range.	US/CA/IN/International
carrier_id	Identifier of the carrier serving the phone number	US/CA/IN/International
carrier_name	Name of the carrier serving the phone number	US/CA/IN/International
number_type	Type of Phone Number Supported	US/CA/IN/International
country_iso_code	The 3 letter ISO code of the country	US/CA/IN/International
country	The name of the country the phone number belongs to	US/CA/IN/International
carrier_mcc	Mobile Network code of the carrier most recently serving the phone number.	US/CA/IN/International
carrier_mnc	Mobile Network Code of carrier most recently serving the phone number.	US/CA/IN/International
account_type	Type of Account for Valid Ported Mobile Phone number	US/CA
porting_status	The Phone Number has been Ported during its life time.	US/CA
last_known_event	Most recent activity on the Phone Number.	US/CA
porting_date	Indicates the date on which the phone number was ported.	US/CA
previous_carrier_id	Identifier of the carrier previously serving the phone number.	US/CA
previous_carrier_name	Name of the carrier previously serving the phone number.	US/CA
deactivation_date	Date when phone number was deactivated.	US/CA

Appendix C : Phone Verification Service – Headers

Name	Description	Data Type	Size	Example	Default Value
ext_trx_id	Unique identifier that customer can send to track the request/response chain. This is Optional field.	String		“XCT124JXAAWB89”	Value present ONLY if provided ( optional)
ext_reseller_cust_id	This is the identifier of the customer using the PNV Service. This is Optional field.	String	64	"V7229"	Value present ONLY if provided ( optional)
tracking_id	To track the customer transactions	String	38	" 200290035921500446652035"

Phone Number Lookup Response : Examples

Case 1 :
Deactivation Date : November 14th, 2014
Porting Date : November 15th, 2014

{ 
"numberidentity":  
{ 
"number": "+167893XXXXX", 
"validity": "true", 
"carrier_id": "3022", 
"carrier_name": "METRO PCS INC.", 
"number_type": "M", 
"country_iso_code": "USA", 
"country": "United States", 
"carrier_mcc": "311", 
"carrier_mnc": "660", 
"account_type": "Postpaid", 
"last_known_event": "Ported", 
"porting_date": "2014-11-15T00:00Z", 
"previous_carrier_id": "3022", 
"previous_carrier_name": "SPRINT." 
} 
, 
"ext_trx_id": "sample_ext_trx_id",
"ext_reseller_cust_id": "123456", 
"tracking_id": "200290035921500446652035" 
}

Case 2 :
Deactivation Date : November 14th, 2014
Porting Date : November 13th, 2014

{ 
"numberidentity":  
{ 
"number": "+167893XXXXX", 
"validity": "true", 
"carrier_id": "3022", 
"carrier_name": "METRO PCS INC.", 
"number_type": "M", 
"country_iso_code": "USA", 
"country": "United States", 
"carrier_mcc": "311", 
"carrier_mnc": "660", 
"account_type": "Postpaid", 
"last_known_event": "Ported", 
"porting_date": "2014-11-13T00:00Z", 
"previous_carrier_id": "3022", 
"previous_carrier_name": "SPRINT." 
} 
, 
"tracking_id": "200290035921500446656695" 
}

Case 3 :
Deactivation Date : November 14th, 2014
Porting Date : November 14th, 2014

{ 
"numberidentity":  
{ 
"number": "+167893XXXXX", 
"validity": "true", 
"carrier_id": "3022", 
"carrier_name": "METRO PCS INC.", 
"number_type": "M", 
"country_iso_code": "USA", 
"country": "United States", 
"carrier_mcc": "311", 
"carrier_mnc": "660", 
"account_type": "Postpaid", 
"last_known_event": "Ported", 
"porting_date": "2014-11-14T00:00Z", 
"previous_carrier_id": "3022", 
"previous_carrier_name": "SPRINT." 
} 
, 
"tracking_id": "200290035921500446652977" 
}

Phone Verification API documentation version 5.0.0

About Phone Verification

numberidentity

/numbers/{number} get

get /numbers/{number}

URI Parameters

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 402

Body

HTTP status code 403

Body

HTTP status code 404

HTTP status code 409

Body

HTTP status code 412

Body

HTTP status code 429

Body

HTTP status code 500

Body

HTTP status code 503

Phone Number Monitoring Service:

Business Events

Appendix A : Phone Verification Service – Lookup Attributes

Appendix B : Phone Verification Service – International Coverage

Appendix C : Phone Verification Service – Headers

Phone Number Lookup Response : Examples