Contents

Identity Gateway API

Introduction

Identity Gateway is an API that provides identity graph data with support multiple inputs and results. 

The URI contains both the input data for search as well as the requested output elements. 

Pricing is a function of the type of request (some requests are based on input such as Caller-ID and Line Status while others on data returned such as Email Append or Phone Append) and upon number of elements requested and returned (such a a price for a mobile number returned and a separate price for email returned)

General Syntax and Usage

All requests are performed via API GET action and include a dynamic set of variables based on input data and requested result data.  Input types & variables and requested result data are explained in greater detail below. 

ItemDescriptionExample
API EndpointURL of requesthttps://{hostname}.digitalsegment.com/RestServices/gateway/{version}/ds
API KeyGenerated for use within your accountapi-key=abc345kk8sdfsdf
FormatThe format variable allows the user to choose between XML or JSON formatted response. JSON is defaultformat=xml
RequestIndicates the elements to be requested for the queryrequest=email,name,address,landline,wireless,active
Input TypeIndicated the element(s) to be used for inputinput=phone
Input DataThe input value(s). Defined further in next sectionphone=7705551212

Example Query string:
https://{host}.digitalsegment.com/RestServices/gateway/{version}/ds?api-key=abc345kk8&format=json&request=email,name,address&input=phone&phone=7705551212

BOLD values indicate Query String Variables
ITALIC values indicate User provided elements

				
					https://{host}.digitalsegment.com/RestServices/gateway/{version}/ds?api-key=abc345kk8&format=json&request=email,name,address&input=phone&phone=7705551212
				
			

Input Types and Variables

Identity Gateway will accept various Input data to perform the requested operations. The required data elements are based on the type on Input chosen.

Input TypeRequired Varibles
phonephone
businessbusiness, address, city, state, zipcode
personfirstname, lastname, address, city, state, zipcode
emailemail
maid (coming soon)maid
ipip
hashhash, hashtype (MD5, SHA1, SHA256)
intperson*lastname, firstname, *city, zipcode, street, bldnum, address, province, country* (2 Char ISO)
intphonephone (without country code), country (2 Char ISO)

Request Types

Each request type provided will return various data based on Input data and other requested results. All requested results will utilize any Input data as well as any upstream search result data. 
Example:  If your Input data contains Person detail and your Request includes wireless, landline, active”, all found phone numbers will also be passed into the active, carrier, cnam portions of the request if chosen.  

Request TypeDescription
landlineReturns Land Line phone number
wirelessReturns Wireless phone number
addressReturns the result address associated to the result
nameReturns the Name associated to the result
cnamReturns Caller-ID detail for any resulting or Input Phone Number
activeReturns the Active\Inactive status for any resulting or Input Phone Number
carrierReturns the Carrier status for any resulting or Input Phone Number
linetypeReturns the Line Type for any resulting or Input Phone Number
emailReturns Email Address associated to the result
cassReturns the USPS CASS result for any resulting or Input address
dpvReturns the USPS DPV result for any resulting or Input address
demo (coming soon)Returns a selected set of demographic detail for the resulting or Input Name and Address combination
ip (coming soon)Returns IP Address associated to the resulting or Input name and address, phone
internationalReturns International Phone Append or Reverse Phone Append dependant on Input Type "intphone"or "intperson"

API Response Objects

Each component of the Input and Request is returned in a JSON or XML formatted response. Sample full response below:

				
					{
    "input": {
        "phone": "7275551212"
    },
    "result": {
        "active": {
            "found": true,
            "input": {
                "found": true,
                "activestatus": "yes"
            }
        },
        "cnam": {
            "found": true,
            "input": {
                "found": true,
                "cnam": "Some Name"
            }
        },
        "address": {
            "found": true,
            "address1": "123 Here St",
            "city": "SOMEWHERE",
            "state": "NC",
            "zipcode": "12345"
        },
        "carrier": {
            "found": true,
            "input": {
                "found": true,
                "lrn": "18134049547",
                "spid": "6006",
                "ocn": "6502",
                "lata": "952",
                "city": "TAMPA",
                "state": "FL",
                "jurisdiction": "INDETERMINATE",
                "lec": "CELLCO PARTNERSHIP DBA VERIZON"
            }
        },
        "linetype": {
            "found": true,
            "input": {
                "found": true,
                "linetype": "WIRELESS"
            }
        }
    },
    "transaction": {
        "queries": {
            "ActiveStatusSuccess": -0.01,
            "ALineTypeSuccess": 0,
            "ACarrierSuccess": -0.0099,
            "CNAMSuccess": -0.008,
            "GWWPAReverseSuccess": 0
        },
        "total": -0.0558,
        "accountbalance": -2.4615
    },
    "status": true
}
				
			

Input Object

The Input Object displays the information passed into the search. This object will contain the same elements passed without modification. In the example below, the user has provided the ïnput = “phone” and provided the required variable of phone with a value of “7275551212”. This would be represented as the following URL string:

				
					input=phone&phone=7705551212
				
			
				
					{ "input": { "phone": "7275551212" } }
    
				
			

Result Object

The Result Object contains all requested result objects associated to the users “request=” values. The objects contained in the Result object are named exactly as defined in “Request Types and Descriptions”section of this document. Example below will result in several Request elements contained in the Result Object.

				
					request=active,cnam,address
				
			
				
					{
    "result": {
        "active": {
            "found": true,
            "input": {
                "found": true,
                "activestatus": "yes"
            }
        },
        "cnam": {
            "found": true,
            "input": {
                "found": true,
                "cnam": "Some Name"
            }
        },
        "address": {
            "found": true,
            "address1": "123 Here St",
            "city": "SOMEWHERE",
            "state": "NC",
            "zipcode": "12345"
        }
				
			

Name response object

The Name result object contains the result of a request with “name”.

Example below will result in the “name” object contained in the Result object.

				
					request=name
				
			
				
					"name": {
            "found": true,
            "firstname": "SOME",
            "lastname": "NAME"
        }
				
			
VariableDescription
found"true" if returned
firstnameFirst Name of result
lastnameLast Name of result

Address response object

The Name result object contains the result of a request with “name”.

Example below will result in the “name” object contained in the Result object.

				
					request=address
				
			
				
					"address": {
            "found": true,
            "address1": "123 Here St",
            "address2": "Suite A",
            "city": "Somewhere",
            "state": "AL",
            "zipcode": "12345",
            "zipcode4": "4321"
        }
				
			
VariableDescription
found"true" if returned // "false" if not found
address1Address Line of result
address2Second Line address of result
cityCity Line address of result
stateState Line address of result
zipcode5 digit zipcode of result
zipcode44 digit zip code/delivery point of result

Landline response object

The Landline result object contains the result of a request with “landline”.

Example below will result in the “landline” object contained in the Result object. If the result is found, a match can be made at the Full Name + Address = Individual Match (“I”) or Last Name + Address = Family Match (“F”)

				
					request=landline
				
			
				
					"landline": {
            "found": true,
            "phone": "7275551212",
            "matchtype": "F"
        }
				
			
VariableDescription
found"true" if returned // "false" if not found
phonePhone Number of result
matchtypeMatch Type of result. "I"= Individual Match, "F"= Family/Surname Match

Wireless response object

The Wireless result object contains the result of a request with “wireless”.

Example below will result in the “wireless” object contained in the Result object. If the result is found, a match can be made at the Full Name + Address = Individual Match (“I”) or Last Name + Address = Family Match (“F”)

				
					request=landline
				
			
				
					"wireless": {
            "found": true,
            "phone": "7705551212",
            "matchtype": "F"
        }
				
			
VariableDescription
found"true" if returned // "false" if not found
phonePhone Number of result
matchtypeMatch Type of result. "I"= Individual Match, "F"= Family/Surname Match

Active response object

The Active result object contains the result of a request with “active”. If requested, the “active” request will check the Active\Inactive status of any and all of the Input Phone, Wireless Phone, Landline Phone.

Example below will result in the “active” object contained in the Result object. Each phone number being checked will be contained in a sub-object indicating which phone number was checked and its status.

				
					request=active
				
			
				
					 "active": {
            "found": true,
            "wireless": {
                "found": true,
                "activestatus": "yes"
            },
             "landline": {
                "found": true,
                "activestatus": "yes"
            }
        }
				
			
VariableDescription
found"true" if returned // "false" if not found
activestatusStatus of Phone Number of result or input. Yes=Active, No=Inactive

Cnam response object

The Cnam result object contains the result of a request with “cnam”. If requested, the “cnam” request will check and return the Caller-ID information for any and all of the Input Phone, Wireless Phone, Landline Phone.

Example below will result in the “cnam” object contained in the Result object. Each phone number being checked will be contained in a sub-object indicating which phone number was checked and its status.

				
					request=cnam
				
			
				
					"cnam": {
    "found": true,
    "input": {
        "found": true,
        "cnam": "SOME NAME"
    }
}
				
			
VariableDescription
found"true" if returned // "false" if not found
cnamCaller ID inforamtion as returned by the Telecom Carrier

Linetype response object

The Line Type result object contains the result of a request with “linetype”. If requested, the “linetype” request will check and return the Caller ID information for any and all of the Input Phone, Wireless Phone, Landline Phone.

Example below will result in the “linetype” object contained in the Result object. Each phone number being checked will be contained in a sub-object indicating which phone number was checked and its line type.

				
					request=linetype
				
			
				
					"linetype": {
            "found": true,
            "input": {
                "found": true,
                "linetype": "LANDLINE"
            }
        }
				
			
VariableDescription
found"true" if returned // "false" if not found
linetypeLine Type inforamtion as returned by the Telecom Carrier. Values include: WIRELESS, LANDLINE, VoIP

Carrier response object

The Carrier result object contains the result of a request with “carrier”. If requested, the “carrier” request will check and return the full and complete Carrier information for any and all of the Input Phone, Wireless Phone, Landline Phone.

Example below will result in the “carrier” object contained in the Result object. Each phone number being checked will be contained in a sub-object indicating which phone number was checked and its carrier detail.

If you need further definition of this result object, please let your account manager know.

				
					request=carrier
				
			
				
					"carrier": {
            "found": true,
            "input": {
                "found": true,
                "lrn": "17622046000",
                "spid": "7125",
                "ocn": "8392",
                "lata": "438",
                "city": "CALHOUN",
                "state": "GA",
                "jurisdiction": "INDETERMINATE",
                "lec": "TELEPORT COMMUNICATIONS AMERIC"
            }
        }
				
			

Email response object

The Email result object contains the result of a request with “email”. If requested, the “email” request will check and return the email address associated to the Input Name and Address or the resulting Name and Address from a reverse contact search.

Example below will result in the “email” object contained in the Result object.

				
					request=email
				
			
				
					 "email": {
            "found": true,
            "email": "someemail@domain.net",
            "matchtype": "I"
        },

				
			
VariableDescription
found"true" if returned // "false" if not found
emailEmail Address associated with Input or Result information
matchtypeType of match that returned Email Address. I=Individual, F=Family, A=Address

DPV response object

The DPV result object contains the USPS Delivery Point Processing result of a request with “dpv”. If requested, the “dpv” request will check and return the Delivery Point processing results associated to the Input or Resulting Address.

The sample below will result in the “dpv” object contained in the Result object.

If you require additional description of these common USPS elements, please let your account manager know.

				
					request=dpv
				
			
				
					"dpv": {
            "found": true,
            "add1": "123 MAIN ST",
            "city": "SOMEWHERE",
            "state": "FL",
            "zip5": "12345",
            "zip4": "2315",
            "carrier": "C001",
            "dpvcheck": "8",
            "dpvcode": "24",
            "dpvaddrtype": "S",
            "nondeliv": "N",
            "dpvcompstatus": "0000000003333",
            "dpvresult": "Y",
            "dpvnotes": "AA BB"
        }
				
			

CASS response object

The CASS result object contains the USPS Address Standardization Processing result of a request with “cass”. If requested, the “cass” request will check and return the CASS processing results associated to the Input or Resulting Address. The process also breaks apart Name and Business information to aid in Name parsing processes.

Status code of “X” represents a failed CASS address.

The sample below will result in the “cass” object contained in the Result object.

				
					request=cass
				
			
				
					"cass": {
            "found": true,
            "city": "SOMEWHERE",
            "namepart1": "FIRSTNAME",
            "namepart2": "LASTNAME",
            "streetnumber": "123",
            "predirection": "W",
            "streetname": "MAIN",
            "streetsuffix": "ST",
            "state": "NJ",
            "statuscode": "9",
            "firm": "BUSINESS NAME",
            "zip4": "2315",
            "address1": "123 W MAIN ST",
            "zip": "12345"
        }
				
			

Demographics response

This feature will be added in the near future

				
					request=demo
				
			
				
					"demo": {
            "found": true,
            "elementname":"value"
        }
				
			

International response

The International response contains either the International Reverse Phone Append result or International Phone Append result dependent upon the type of Input specified. “intperson” input type would imply search for a phone number while “intphone”input type would imply searching for the person associated to a phone number.  Multiple results can be returned within the result object based on input data. If the query is a broad search (lastname, city), you may receive up to 50 results.  If the Input information is very specific, Digital Segment will continue to search based on the following methods: Full Information presented, Surname with Address, Surname and City.

				
					request=international
				
			

International Reverse Phone Append Result Syntax

				
					 "international": {
            "found": true,
            "records": [
                {
                    "residential": "1",
                    "name": {
                        "lastname": "A B",
                        "full_firstname": "JOSE LOUIS SANCHEZ",
                        "short_firstname": "JOSE LOUIS SANCHEZ",
                        "full_name": "A B JOSE LOUIS SANCHEZ",
                        "full_short_name": "A B JOSE LOUIS SANCHEZ"
                    },
                    "address": {
                        "city": "LISBOA",
                        "street": "CAMINHO ALTO VAREJAO 20 1 E",
                        "bldnum": "20",
                        "full_street": "CAMINHO ALTO VAREJAO 20 1 E 20",
                        "full_city": " LISBOA"
                    },
                    "phone": {
                        "type": "TEL",
                        "suffix": "218131446",
                        "phone": "218131446"
                    }
                }
            ]
        }
				
			

International Phone Append Result Syntax

				
					"international": {
            "found": true,
            "records": [
                {
                    "residential": "1",
                    "name": {
                        "lastname": "MONTERO",
                        "full_firstname": "LAURA SANCHEZ",
                        "short_firstname": "LAURA SANCHEZ",
                        "full_name": "MONTERO LAURA SANCHEZ",
                        "full_short_name": "MONTERO LAURA SANCHEZ"
                    },
                    "address": {
                        "city": "LISBOA",
                        "street": "R JOAO DE CASTILHO 13 R/C E",
                        "bldnum": "13",
                        "full_street": "R JOAO DE CASTILHO 13 R/C E 13",
                        "full_city": " LISBOA"
                    },
                    "phone": {
                        "type": "TEL",
                        "suffix": "213643399",
                        "phone": "213643399"
                    }
                },
                {
                    "residential": "1",
                    "name": {
                        "lastname": "BARBOSA",
                        "full_firstname": "RODRIGO PALMA LEAO SANCHEZ",
                        "short_firstname": "RODRIGO PALMA LEAO SANCHEZ",
                        "full_name": "BARBOSA RODRIGO PALMA LEAO SANCHEZ",
                        "full_short_name": "BARBOSA RODRIGO PALMA LEAO SANCHEZ"
                    },
                    "address": {
                        "city": "LISBOA",
                        "street": "TV D VASCO 35 1 D",
                        "bldnum": "35",
                        "full_street": "TV D VASCO 35 1 D 35",
                        "full_city": " LISBOA"
                    },
                    "phone": {
                        "type": "TEL",
                        "suffix": "213645007",
                        "phone": "213645007"
                    }
                } 
            ] 
        }
				
			

Transaction response

Each use of the API will contain a Transaction object within the Result object of the response. The Transaction object informs the user of queries ran, billable cost for those queries as well as current account balance for the month. Objects contained in the Transaction object are related specifically to the requested responses.

Queries roll up to a total for the transaction which is then added to the Account section which displays the current balance remaining or balance due at month end.

				
					"transaction": {
        "queries": {
            "Wireless Reverse": -0.01,
            "CASS": -0.001,
            "Active Status": -0.01,
            "CallerID": -0.01
        },
        "total": -0.031,
        "accountbalance": 9.026
    }