Page tree
Skip to end of metadata
Go to start of metadata



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/PhoneInfo/{PHONENUMBER}/{TESTTYPE}/{LICENSEKEY}?format=json


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


PhoneInfoPhoneInfo[]VariesThe returned values of a valid phone number.
ErrorObjectVariesThe returned error result from a failed address verification or user input error.
DebugString[]VariesUsed internally for testing.


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.

SMSAddressStringVariesThe SMS Gateway Address for a wireless number.
MMSAddressStringVariesThe MMS Gateway Address for a wireless number.
DateFirstSeenStringVariesThis value represents the date the contact data was last updated.
DateOfPortingStringVariesThis value represents the date a number was ported from one carrier to another.
NoteCodesStringVariesThis value represents specific test result codes resulting from true statements about the test. See Descriptions Below.
NoteDescriptionsStringVariesThis 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".

LatitudeStringVariesThe latitude of the registered contact.
LongitudeStringVariesThe longitude of the registered contact.
SICCodeStringVariesThe 8 digit Standard Industrial Classification related to business contact.
SICDescStringVariesThe 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

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

  • No labels