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)
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.
| Item | Description | Example |
|---|---|---|
| API Endpoint | URL of request | https://{hostname}.digitalsegment.com/RestServices/gateway/{version}/ds |
| API Key | Generated for use within your account | api-key=abc345kk8sdfsdf |
| Format | The format variable allows the user to choose between XML or JSON formatted response. JSON is default | format=xml |
| Request | Indicates the elements to be requested for the query | request=email,name,address,landline,wireless,active |
| Input Type | Indicated the element(s) to be used for input | input=phone |
| Input Data | The input value(s). Defined further in next section | phone=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
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 Type | Required Varibles |
|---|---|
| phone | phone |
| business | business, address, city, state, zipcode |
| person | firstname, lastname, address, city, state, zipcode |
| maid | maid |
| ip | ip |
| hash | hash, Must Include variable:hashtype (acceptable values:MD5, SHA1, SHA256) |
| intperson | *lastname, firstname, *city, zipcode, address, province, country* (2 Char ISO) |
| intphone | phone (without country code), country (2 Char ISO) |
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 Type | Description |
|---|---|
| landline | Returns Land Line phone number |
| wireless | Returns Wireless phone number |
| address | Returns the result address associated to the result |
| name | Returns the Name associated to the result |
| cnam | Returns Caller-ID detail for any resulting or Input Phone Number |
| active | Returns the Active\Inactive status for any resulting or Input Phone Number. By default, only Wireless Numbers are checked. Landlines can be checked with optional parameter |
| carrier | Returns the Carrier status for any resulting or Input Phone Number |
| linetype | Returns the Line Type for any resulting or Input Phone Number |
| Returns Email Address associated to the result | |
| cass | Returns the USPS CASS result for any resulting or Input address |
| dpv | Returns the USPS DPV result for any resulting or Input address |
| listtype | Returns the Listing Type (Res\Bus) for any resulting or Input Phone Number(s) |
| demographics | Returns a selected set of demographic detail for the resulting or Input Name and Address combination. Additional options below. |
| ip | Returns IP Address associated to the resulting or Input name and address, phone |
| international | Returns International Phone Append or Reverse Phone Append dependant on Input Type "intphone"or "intperson" if the Country supports the results |
| deactivation | Returns Mobile Phone change data (Deactivation\Resume\Suspend\Change) |
| eval | validate Email Address in either Input or in append data |
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
}
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" } }
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"
}
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"
}
| Variable | Description |
|---|---|
| found | "true" if returned |
| firstname | First Name of result |
| lastname | Last Name of result |
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"
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| address1 | Address Line of result |
| address2 | Second Line address of result |
| city | City Line address of result |
| state | State Line address of result |
| zipcode | 5 digit zipcode of result |
| zipcode4 | 4 digit zip code/delivery point of result |
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"
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| phone | Phone Number of result |
| matchtype | Match Type of result. "I"= Individual Match, "F"= Family/Surname Match |
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=wireless
"wireless": {
"found": true,
"phone": "7705551212",
"matchtype": "F"
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| phone | Phone Number of result |
| matchtype | Match Type of result. "I"= Individual Match, "F"= Family/Surname Match |
The Active result object contains the result of a request with “active”. If requested, by default, the “active” request will check the Active\Inactive status of any and all of the Input Phones, Wireless Phones, and Landline Phones. NOTE: ONLY WIRELESS PHONES WILL RETURN STATUS unless optional variable used (see below).
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.
Optional variable activelandline=yes will allow for Landline phone numbers to be checked for Active Status.
request=active
"active": {
"found": true,
"wireless": {
"found": true,
"activestatus": "yes"
}
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| activestatus | Status of Phone Number of result or input. Yes=Active, No=Inactive |
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"
}
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| cnam | Caller ID inforamtion as returned by the Telecom Carrier |
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"
}
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| linetype | Line Type inforamtion as returned by the Telecom Carrier. Values include: WIRELESS, LANDLINE, VoIP |
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"
}
}
The List Type result object contains the result of a request with “listtype”. If requested, the “listtype” request will check and return the List Type detail from Landline subscriber databases for the Input Phone or Landline Phones returned as part of an append request.
Example below will result in the “listtype” 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 list type detail.
If you need further definition of this result object, please let your account manager know.
request=listtype
"listtype": {
"found": true,
"input": {
"found": true,
"type": "Bus"
}
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| type | Either Res or Bus |
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"
},
| Variable | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| Email Address associated with Input or Result information | |
| matchtype | Type of match that returned Email Address. I=Individual, F=Family, A=Address |
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"
}
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 request has many options for the calling service to choose from. The default result set is detailed below. Using the option “demorequest” variable, you can specify different types of result data to add to the default response. Additionally, you can specify multiple options separated by commas (realestate,finance). Additionally, the option to use the Name associated with the demographics response for other searches. This is used in the event of an unknown person name.
usedemoname=yes – will utilize the Name fields in the Demographic response for future searchs like Email Append or Phone Append.
demorequest=householdcomp – will return data correlating to Household Composition.
demorequest=realestate – will return data correlating to Property and Real Estate.
demorequest=interestspurchases – will return data specific to buying behavior and interests.
demorequest=financial – will return data specific to household and person finances.
For a complete list of fields and values, please contact your account manager.
request=demographics (default)
"demographics": {
"found": true,
"matchtype": "address_fullname",
"records": {
"countycode": "063",
"countyname": "Grundy",
"dpv_code": "Y",
"dwellingtype": "S",
"latitude": "41.359600",
"longitude": "-88.413900",
"persondateofbirthmonth": "3",
"persondateofbirthyear": "1955",
"personeducation": "U",
"personexactage": "66",
"personfirstname": "JOHN",
"persongender": "M",
"personlastname": "DOE"
}
}
}
request=demographics
demorequest=householdcomp
"demographics": {
"found": true,
"matchtype": "address_fullname",
"records": {
"countycode": "063",
"countyname": "Grundy",
"dpv_code": "Y",
"dwellingtype": "S",
"latitude": "41.359600",
"longitude": "-88.413900",
"persondateofbirthmonth": "3",
"persondateofbirthyear": "1955",
"personeducation": "U",
"personexactage": "66",
"personfirstname": "JOHN",
"persongender": "M",
"personlastname": "DOE",
"ChildrenAge00_02": "U",
"ChildrenAge00_02Female": "U",
"ChildrenAge00_02Male": "U",
"ChildrenAge00_02Unknown": "U",
"ChildrenAge03_05": "U",
"ChildrenAge03_05Female": "U",
"ChildrenAge03_05Male": "U",
"ChildrenAge03_05Unknown": "U",
"ChildrenAge06_10": "U",
"ChildrenAge06_10Female": "U",
"ChildrenAge06_10Male": "U",
"ChildrenAge06_10Unknown": "U",
"ChildrenAge11_15": "U",
"ChildrenAge11_15Female": "U",
"ChildrenAge11_15Male": "U",
"ChildrenAge11_15Unknown": "U",
"ChildrenAge16_17": "U",
"ChildrenAge16_17Female": "U",
"ChildrenAge16_17Male": "U",
"ChildrenAge16_17Unknown": "U",
"Females_18_24": "U",
"Females_25_34": "U",
"Females_35_44": "U",
"Females_45_54": "U",
"Females_55_64": "U",
"Females_65_74": "U",
"Females_75_Plus": "U",
"GenerationsInHousehold": "1",
"Grandchildren": "U",
"Males_18_24": "U",
"Males_25_34": "Y",
"Males_35_44": "U",
"Males_45_54": "U",
"Males_55_64": "U",
"Males_65_74": "U",
"Males_75_Plus": "U",
"NumberOfAdults": "1",
"numberofpersonsinlivingunit": "1",
"personagecode": "10",
"personmaritalstatus": "S",
"presenceofchildren": "N",
"Unknowngender_18_24": "U",
"Unknowngender_25_34": "U",
"Unknowngender_35_44": "U",
"Unknowngender_45_54": "U",
"Unknowngender_55_64": "U",
"Unknowngender_65_74": "U",
"Unknowngender_75_Plus": "U"
}
}
request=demographics
demorequest=realestate
"demographics": {
"found": true,
"matchtype": "address_fullname",
"records": {
"countycode": "063",
"countyname": "Grundy",
"dpv_code": "Y",
"dwellingtype": "S",
"latitude": "41.359600",
"longitude": "-88.413900",
"persondateofbirthmonth": "3",
"persondateofbirthyear": "1955",
"personeducation": "U",
"personexactage": "66",
"personfirstname": "JOHN",
"persongender": "M",
"personlastname": "DOE",
"deeddateofrefinanceday": "13",
"deeddateofrefinancemonth": "12",
"deeddateofrefinanceyear": "2010",
"estimatedcurrenthomevaluecode": "G",
"estimatedincomecode": "N",
"homeownerprobabilitymodel": "H",
"homepurchasedateday": "17",
"homepurchasedatemonth": "12",
"homepurchasedateyear": "2010",
"homepurchaseprice": "156",
"homepurchasepricecode": "3",
"homeyearbuilt": "1900",
"lengthofresidencecode": "10",
"mortgageamountinthousandscode": "3",
"mortgagelendername": "GRUNDY BK",
"mortgagelendernameavailable": "Y",
"mortgageloantype": "C",
"mortgageratetype": "U",
"MostRecentLenderCode": "000",
"MostRecentLenderName2nd": "U",
"MostRecentMortgage2ndInterestRate": "U",
"MostRecentMortgage2ndInterestRateType": "U",
"MostRecentMortgage2ndLoanTypeCode": "U",
"MostRecentMortgageAmount2nd": "U",
"MostRecentMortgageDate2nd": "U",
"MostRecentMortgageInterestRate": "000000",
"Purchase2ndMortgageAmount": "00000000",
"Purchase2ndMortgageLoanTypeCode": "U",
"PurchaseLenderCode": "000",
"PurchaseMortgageDate": "20101213",
"refinanceamountinthousandscode": "3",
"refinancelendernameavailable": "Y"
}
}
request=demographics
demorequest=interestspurchases
"demographics": {
"found": true,
"matchtype": "address_fullname",
"records": {
"countycode": "063",
"countyname": "Grundy",
"dpv_code": "Y",
"dwellingtype": "S",
"latitude": "41.359600",
"longitude": "-88.413900",
"persondateofbirthmonth": "3",
"persondateofbirthyear": "1955",
"personeducation": "U",
"personexactage": "66",
"personfirstname": "JOHN",
"persongender": "M",
"personlastname": "DOE",
"ArtsAndAntiquesAntiques": "U",
"ArtsAndAntiquesArt": "Y",
"AutomotiveAutoPartsAndAccessories": "U",
"automotivebuff": "U",
"Autowork": "U",
"Aviation": "U",
"BeautyCosmetics": "U",
"BoatingSailing": "U",
"bookbuyer": "U",
"bookreader": "U",
"BooksAndMagazinesMagazines": "U",
"BooksAndMusicBooks": "U",
"BooksAndMusicBooksAudio": "U",
"CampingHiking": "U",
"ChildrensApparelInfantsAndToddlers": "U",
"ChildrensCharitableDonation": "U",
"ChildrensInterests": "U",
"ChildrensLearningAndActivityToys": "U",
"ChildrensProductsGeneral": "U",
"ChildrensProductsGeneralBabyCare": "U",
"ChildrensProductsGeneralBackToSchool": "U",
"CollectiblesandAntiquesGrouping": "Y",
"CollectiblesAntiques": "Y",
"CollectiblesArts": "U",
"CollectiblesCoins": "U",
"CollectiblesGeneral": "U",
"CollectiblesSportsMemorabilia": "U",
"CollectiblesStamps": "U",
"CollectorAvid": "U",
"CommunityCharities": "U",
"computerowner": "U",
"ComputingHomeOfficeGeneral": "U",
"ConsumerElectronics": "U",
"cookingenthusiast": "U",
"CookingFoodGrouping": "U",
"CookingGeneral": "U",
"DIYLiving": "U",
"ElectronicsandComputingTVVideoMovieWatcher": "U",
"ElectronicsComputersGrouping": "U",
"ElectronicsComputingAndHomeOffice": "U",
"ExerciseAerobic": "U",
"exerciseenthusiast": "U",
"ExerciseHealthGrouping": "U",
"ExerciseRunningJogging": "U",
"ExerciseWalking": "U",
"Fishing": "U",
"FoodsNatural": "U",
"FoodWines": "U",
"GamesBoardGamesPuzzles": "U",
"GamesComputerGames": "U",
"GamesVideoGames": "U",
"Gaming": "U",
"GamingCasino": "Y",
"Gardener": "U",
"gardening_farmingbuyer": "U",
"health_institutioncontributor": "U",
"HealthAndBeauty": "U",
"HealthMedical": "U",
"Highbrow": "U",
"HighEndAppliances": "U",
"hightechleader": "U",
"HistoryMilitary": "U",
"HomeandGarden": "U",
"homedecoratingenthusiast": "Y",
"HomeFurnishingsDecorating": "U",
"HousePlants": "U",
"Hunting": "U",
"HuntingShooting": "U",
"LifestylesInterestsandPassionsCollectibles": "U",
"Luggage": "U",
"Magazines": "U",
"MailOrderBuyer": "U",
"mailresponder": "U",
"MilitaryMemorabiliaWeaponry": "U",
"Motorcycling": "U",
"MovieCollector": "U",
"MovieMusicGrouping": "U",
"Musicalinstruments": "U",
"MusicAvidListener": "U",
"MusicCollector": "U",
"MusicHomeStereo": "U",
"MusicPlayer": "U",
"Nascar": "U",
"newsandfinancial": "U",
"OnlinePurchasingIndicator": "U",
"opportunityseekers": "U",
"OtherPetOwner": "U",
"outdoorenthusiast": "U",
"OutdoorsGrouping": "U",
"outdoorsportslover": "U",
"Parenting": "U",
"photography": "U",
"PhotographyAndVideoEquipment": "U",
"PoliticalCharitableDonation": "U",
"PoliticalConservativeCharitableDonation": "U",
"politicalcontributor": "U",
"PoliticalLiberalCharitableDonation": "U",
"ReadingAudioBooks": "U",
"ReadingGeneral": "U",
"ReadingGrouping": "U",
"ReadingMagazines": "U",
"ReadingScienceFiction": "U",
"religiouscontributor": "U",
"ReligiousInspirational": "U",
"religiousmagazine": "U",
"ScienceSpace": "Y",
"ScubaDiving": "U",
"SewingKnittingNeedlework": "U",
"Smoker": "U",
"Snowskiing": "U",
"SohoIndicator": "U",
"SpectatorSportsAutoMotorcycleRacing": "U",
"SpectatorSportsBaseball": "U",
"SpectatorSportsBasketball": "U",
"SpectatorSportsFootball": "U",
"SpectatorSportsHockey": "U",
"SpectatorSportsSoccer": "U",
"SpectatorSportsTVSports": "U",
"SportsandLeisure": "U",
"SportsGrouping": "U",
"SportyLiving": "U",
"sweepstakes": "U",
"Tennis": "U",
"TheaterPerformingArts": "U",
"TravelAndEntertainmentCardHolder": "U",
"TravelCruiseVacations": "U",
"TravelDomestic": "U",
"traveler": "Y",
"TravelGrouping": "Y",
"TravelInternational": "U",
"TVCable": "U",
"TVSatelliteDish": "U",
"UpscaleLiving": "U",
"Woodworking": "U",
"YoungMensApparel": "U",
"YoungWomensApparel": "U"
}
}
request=demographics
demorequest=financial
"demographics": {
"found": true,
"matchtype": "address_fullname",
"records": {
"countycode": "063",
"countyname": "Grundy",
"dpv_code": "Y",
"dwellingtype": "S",
"latitude": "41.359600",
"longitude": "-88.413900",
"persondateofbirthmonth": "3",
"persondateofbirthyear": "1955",
"personeducation": "U",
"personexactage": "66",
"personfirstname": "JOHN",
"persongender": "M",
"personlastname": "DOE",
"americanexpresscard": "U",
"AmericanExpressGoldPremium": "U",
"Credit_RangeOfNewCredit": "U",
"CreditCardholderUnknownType": "Y",
"CreditCardNewIssue": "U",
"CreditCardUser": "Y",
"CreditRating": "C",
"DiscoverGoldPremium": "U",
"DiscoverRegular": "U",
"GasDeptRetailCardHolder": "U",
"InvestingFinanceGrouping": "U",
"investment": "U",
"InvestmentEstimatedResidentialPropertiesOwned": "U",
"InvestmentsForeign": "U",
"InvestmentsPersonal": "U",
"InvestmentsRealEstate": "U",
"investmentstocksecurities": "U",
"MastercardGoldPremium": "U",
"MastercardRegular": "Y",
"Networth": "G",
"NumberOfLinesOfCredit": "U",
"PresenceOfBankCard": "U",
"PresenceOfCreditCard": "Y",
"presenceofgoldorplatinumcreditcard": "U",
"PresenceOfPremiumCreditCard": "U",
"PresenceOfUpscaleRetailCard": "U",
"refinanceloantype": "C",
"refinanceratetype": "U",
"VisaGoldPremium": "U",
"VisaRegular": "U"
}
}
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
Coming Soon: International Reverse Phone Append Result Syntax
International Phone Append Result Syntax
"international": {
"found": true,
"records": [
{
"isPublished": true,
"isResidential": true,
"businessName": "de Paco Martínez María",
"address1": "CL TONICO SANSANO MORA 4",
"postCode": "03204",
"city": "Elche",
"cityCode": "030651",
"province": "Alicante",
"provinceCode": "03",
"region": "Comunidad Valenciana",
"regionCode": "VAL",
"country": "Spain",
"countryCode": "ES",
"phoneOrMobile": "865 680 900",
"phone": "865 680 900",
"geoLevel": 3,
"geoLevelDescription": "House",
"longitude": "-0.7119617",
"latitude": "38.2567240"
},
{
"isPublished": true,
"isResidential": true,
"businessName": "PACO MARTINEZ 2018 S.L.",
"address1": "CL FULGENCIO BADAL (MUSICO) 0",
"postCode": "12600",
"city": "La Vall d'Uixó",
"cityCode": "121264",
"province": "Castellón",
"provinceCode": "12",
"region": "Comunidad Valenciana",
"regionCode": "VAL",
"country": "Spain",
"countryCode": "ES",
"phoneOrMobile": "964 747 796",
"phone": "964 747 796",
"geoLevel": 2,
"geoLevelDescription": "Street",
"longitude": "-0.2318430",
"latitude": "39.8274517",
"isBusiness": true
}
The Deactivation response contains transaction detail regarding changes reported by the Mobile Carriers (MSP’s). Details provided in the response allow for understanding of activity regarding the status of a mobile phone number. Land line phone numbers will be searched but will generally not return a result
request=deactivation
Deactivation Result Syntax
"deactivation": {
"input": {
"found": true,
"results": {
"Result": "Success",
"Phone": "18026883918",
"ResultRecords": 2,
"0": {
"MSISDN": "18026883918",
"timeStamp": "2021-07-11",
"OperatorName": "ATTWirelessUS",
"MSISDNEvent": "MDN Deactivation",
"MSISDNNew": null,
},
"1": {
"MSISDN": "18026883918",
"timeStamp": "2016-07-09",
"OperatorName": "SprintUS",
"MSISDNEvent": "MDN Deactivation",
"MSISDNNew": null,
}
}
}
| Key Name | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| results | Header for results array |
| Result | Success or Failure - Indicates if result(s) were found for the number searched |
| Phone | Input Phone Number for results being returned |
| ResultRecords | Amount of result sets being returned |
| Index of result records | Contains an array of results ordered and numbered |
| timeStamp | Date of record provided by MSP |
| MSISDN | MSP Carrier returned phone number. Includes country code |
| MSISDNEvent | Transaction type as reported by the MSP. See table below for possible values and descriptions |
| MSISDNNew | If a new phone number is associated to the transaction, the number will be shown here. Typically this is populated on MDN Transfer events |
| OperatorName | Name of MSP reporting transaction |
| MSISDNEvent | Description |
|---|---|
| MDN Deactivation | Phone Number has been reported as Deactived by the MSP |
| MDN Resume | Phone Number has been reported as Resumed by the MSP |
| MDN Suspend | Phone Number has been reported as Suspended by the MSP |
| MDN Transfer | Phone Number has been reported as Transfered\Changed by the MSP |
| No PSMS | No description provided by the MSP |
The Email (eval) response contains detail regarding the current state of the email address. This will provide many different response flags for certain email addresses.
request=eval
Email Validation Result Syntax
"eval": {
"found": true,
"result": "valid",
"flags": [
"free_email_host",
"has_dns",
"smtp_connectable"
]
}
| Key Name | Description |
|---|---|
| found | "true" if returned // "false" if not found |
| result | Summarized State of Email Address |
| flags | Object of Email Flags returned |
| Email Result | Description |
|---|---|
| valid | Email is Valid |
| invalid | Invalid Email Address |
| disposable | A temporary, disposable address. |
| catchall | A domain wide-setting, also known as Accept-all (Unverifiable). |
| unknown | General Error. Please Retry |
| Email Flags | Description |
|---|---|
| Flag | Description |
| has_dns | The input has one or more DNS records associated with the hostname. |
| has_dns_mx | The input has mail exchanger DNS records configured. |
| bad_syntax | The input given doesn't appear to be an email. |
| free_email_host | This email is registered on a free-mail host. (e.g: yahoo.com, hotmail.com) |
| profanity | |
| role_account | This email is a role-based email address (e.g: admin@, help@, sales@) |
| disposable_email | The input given is a disposable email. |
| government_host | The input given is a government email. |
| acedemic_host | The input given is a acedemic email. |
| military_host | The input given is a military email. |
| international_host | INT designated domain names. |
| squatter_host | Host likely intended to look like a big-time provider (type of spam trap). |
| spelling_mistake | The input was misspelled |
| bad_dns | |
| temporary_dns_error | |
| connect_fails | Unable to connect to remote host. |
| accepts_all | Remote host accepts mail at any address. |
| contains_alias | The email address supplied contains an address part and an alias part. |
| contains_subdomain | The host in the address contained a subdomain. |
| smtp_connectable | We were able to connect to the remote mail server. |
| spamtrap_network | Host is affiliated with a known spam trap network. |
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
}