GPPL2 – GetPhoneInfo – Recommended Operation

This document defines the input, output and behavior of the web service operations in GeoPhone Plus. Currently there is only one.

Important Note!
Reverse-phone lookups are subject to federal rules determining who can procure data, and for what purpose. Currently, both disconnected and unlisted numbers return no contact information. GeoPhone Plus 2 returns contact information for connected landline phone numbers as well as wireless ones. Even in the cases that the phone number is disconnected or unlisted, GeoPhone Plus 2 will commonly return the exchange information. GeoPhone Plus 2 can provide information regarding Canadian phone numbers, although GeoPhone Plus 2 Canadian data is not as comprehensive as its US information. You should examine your own business needs first before exploring what GeoPhone Plus 2 can provide.

This is the basic operation for finding the reverse-lookup information. Given a phone number and test type, it will consult national directory-assistance databases to find the owner and address registered. The addresses returned are validated via third party address-validation technique. They are returned to you exactly as the phone carrier releases them. If you need these addresses to be validated, using Service Objects’ AddressValidation web services is highly recommended. Both the contact’s information and the phone company’s information are returned with this operation.
Two valuable bits of information are also retrieved – whether the phone line is for business or residential purposes, and whether the phone line is landline or wireless. By examining the WSDL, you may see that multiple groups of contact/exchange information are possible. Although they are possible in the XML, you will only see one exchange per output, always. It is common, however, to see multiple contacts per phone number (as people change numbers, or there may be multiple businesses at the same phone number.) It is highly recommended that you handle each of these contacts, rather than just the first contact returned.

URL Endpoints

JSON:
- https://trial.serviceobjects.com/gppl2/api.svc/GetPhoneInfoJson?PhoneNumber={PHONENUMBER}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

XML:
- https://trial.serviceobjects.com/GPPL2/api.svc/GetPhoneInfo?PhoneNumber={PHONENUMBER}&TestType={TESTTYPE}&LicenseKey={LICENSEKEY}

GetPhoneInfo Inputs

Name	Type	Description
PhoneNumber	String	10 digit phone number
TestType	String	“FULL”, “BASIC” or “NORMAL”
LicenseKey	String	Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/products/phone/reverse -phone-lookup-service

GetPhoneInfo Outputs

All of the response objects are contained within the PhoneInfoResponse object.

PhoneInfoResponse

Name	Type	Description
PhoneInfo	PhoneInfo[]	Varies	The returned values of a valid phone number.
Error	Object	Varies	The returned error result from a failed address verification or user input error.

PhoneInfo

Name	Type	Description
Providers	Provider	Varies	Contains the Provider object which contains information about the provider associated with the given phone number. This will only return 1 provider per phone number.
Contacts	Contacts[]	Varies	An array of contacts associated with the phone number given. Can be zero to many contacts.
SMSAddress	String	Varies	The SMS Gateway Address for a wireless number.
MMSAddress	String	Varies	The MMS Gateway Address for a wireless number.
DateFirstSeen	String	Varies	This value represents the date the contact data was last updated.
DateOfPorting	String	Varies	This value represents the date a number was ported from one carrier to another.
NoteCodes	String	Varies	This value represents specific test result codes resulting from true statements about the test. See Descriptions Below.
NoteDescriptions	String	Varies	This value represents descriptions matching test codes returned during test.
TokensUsed	String	Varies	The number of tokens used in a given transaction. See Appendix A for details on tokens.

Provider

Name	Type	Description
Name	String	Varies	The name of the line carrier of the phone number (“AT&T”).
City	String	Varies	The city location of the carrier’s exchange (“New York”).
State	String	Varies	The state location of the carrier’s exchange (“NY”).
LineType ^[1]	String	Landline / Wireless / VOIP / Unknown	The type of the phone line, can either be “Landline” “Wireless” “VOIP” or “Unknown”.
Latitude	String	Varies	The latitude of the phone exchange.
Longitude	String	Varies	The longitude of the phone exchange.

Contacts

Name	Type	Description
Name	String	Varies	The name that the phone line is registered to. Can either be a person (“John Doe”) or a business (“Doe Corporation”).
Address	String	Varies	The street address to which the phone line is registered.
City	String	Varies	The city to which the phone line is registered.
State	String	Varies	The state to which the phone line is registered.
PostalCode	String	Varies	The zip code to which the phone line is registered.
PhoneType	String	Residential/Government /Business /Unknown	The type of entity that owns the phone line, will be either “Residential”, “Business”, “Government” or “Unknown”.
Latitude	String	Varies	The latitude of the registered contact.
Longitude	String	Varies	The longitude of the registered contact.
SICCode	String	Varies	The 8 digit Standard Industrial Classification related to business contact.
SICDesc	String	Varies	The description of the 8 digit Standard Industrial Classification.
QualityScore	String	HIGH / MED / LOW	Landlines contacts will return a score of HIGH. Wireless numbers will return a score of HIGH if CallerID match is found with contact name returned. If there is no CallerID match, but a contact is found a score of LOW is returned.

References

^ Reverse Phone Lookup APIs – Differences Between GeoPhone & GeoPhone Plus