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
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. |