• Introduction
• Integration
• Web Service Structure
• Request Types
• Test Types
• Operation Definitions
  • GetPhoneInfo
  • GetPhoneInfo_V2
• Errors
• Frequently Asked Questions
• More Information
  • Appendix A – Tokens: An Advanced Feature
• Conclusion

Introduction

DOTS GeoPhone Plus (referred to as “GeoPhone Plus” or “GPPL”) is a publicly available XML web service that provides reverse phone lookup information about a US (or sometimes Canadian) phone number. The service provides name, address, city and state, along with carrier exchange information.

This is a composite service that combines the datasets from our DOTS GeoPhone and DOTS GeoPhone Wireless services to provide the most comprehensive contact data possible. Landline, wireless and tollfree contact data are all available with one call to the service. GeoPhone Plus can provide instant reverse-phone lookup verification to websites or data enhancement to contact lists. However, the output from GP must be considered carefully before the existence or non-existence of a given phone number is decided.

Integration

Integrating GPPL into your application should be easy and straightforward. If you are using a common platform, ServiceObjects may already have sample code built that you can use:
https://www.serviceobjects.com/sample-code/?service=77

However, if you are using a common platform that does not already have sample code, you can ask ServiceObjects to build you an example. Email support@serviceobjects.com for more details.

Web Service Structure

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic. Web services are too large of a topic to cover in this document, but ServiceObjects has developed its web services to be as easy to integrate and as accessible as possible.
GeoPhone Plus is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link.):
https://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL

This WSDL is the definition of the web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application. Whenever your utilities or IDE asks for a WSDL path to GeoPhone Plus, you can provide this one. Every web service has operations that it offers to subscribers – methods that do different work and return different output. Currently GeoPhone Plus has two operations:

GetPhoneInfo – returns the reverse-phone lookup information about any given phone number, including the name, address, city and state (contact information) and the carrier name, city, state and line type (exchange information).(Deprecated: Use GetPhoneInfo_V2)
GetPhoneInfo_V2 – returns the same reverse-phone lookup information that GetPhoneInfo does with a few notable additions. A connection status and recommendation is added. Also, a new enhanced data source is added that supplements the existing sources. (Recommended operation)
This operation will be described in more detail below…

Each of these operations will be described in detail later in this document.

Request Types

GPPL is a public XML web service that supports SOAP(1.1 and 1.2), POST and GET request methods. A request type is just the type of web (HTTP) request to interact with our web services.
GET – All of the input data is in the query string appended to the url. The response is simple XML.
POST – The input parameters are in the body of the request instead of the query string. The response is simple XML.
SOAP – The input parameters are in and XML SOAP message contained in the body of the request. The response is an XML SOAP message.

Analysis of Request Types

GET is the easiest method to implement by hand because all you have to do is set up the URL and query string. It is also easy to debug because you can test the URL + query string in a web browser and see the output.
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET.
SOAP is the best method if you are using a platform that supports SOAP. In many programming environments you can give your IDE (Integrated Development Environment) the URL to the WSDL of a web service ([https://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL|https://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL]) and it will create a proxy class to help you interact with the web service. In this case you only have to create an instance of the proxy and use its methods. This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any xml parsing.

XML Parsing

If you are not using an environment that creates a proxy class for you to use, then you will have to parse xml. If you do have a proxy, then it uses an xml parser for you. Although xml parsing can be done without a parser, most programming environments provide easy access to several standard ones. We strongly recommend that you take advantage of an xml parser. These parsers may take a few extra minutes to integrate but will give your application an added level of security against improper parsing. Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of xml input properly. Because we have very consistent xml you could get away without this extra precaution, but we suggest you use an xml parser anyway to ensure your application is of the highest quality.

Test Types

Test type only really matters for token users.  For more information on tokens see Appendix A.  For non-token users just submit “FULL” as the test type.

Every call to DOTS GeoPhone Plus requires a test type. A test type is like a key to a set of instructions for how to process a particular call to GPPL. In the case of GPPL, test types are used to determine which datasets to use. Some datasets are more expensive than others and test types can be used to control costs. New test types can freely be added without affecting the data quality or cost for existing users.

As the service matures, new data sources will be added from time to time. If these sources affect cost, new test types will be added. An example of a potential new data source would be disconnected number look-ups which are currently only available in the DOTS Lead Validation service. This check is more costly than the normal checks and so a special test type would be used to perform it. Currently there are only a few available test types, they are:

FULL: – This type currently returns the full available datasets. Landline, wireless,Toll-free and carrier data are all returned when found.
STANDARD: – This type acts as a normal GeoPhone call and returns landline, Toll-free,and carrier data. It does not check for wireless contacts.
More test types will be configured as demand for them is created. But currently these are the only ones needed.

Operation Definitions

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

GetPhoneInfo

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 not validated via any address-validation technique. They are returned to you exactly as the phone carrier releases them. If you need these addresses to be validated, using ServiceObjects’ 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.

GetPhoneInfo Inputs

GetPhoneInfo Outputs

GetPhoneInfo_V2

This operation acts almost identically to the older GetPhoneInfo operation with a few key enhancements. A new data source has been added that supplements/enhances/creates contacts returned by the original operation. This new data source returns name only but adds a large number of accurate contacts (especially wireless ones). This new data set will return more contacts than the previous operation. This is the most complete phone data set available. Also added to this operation are two new outputs. IsConnected returns a flag (TRUE, FALSE or UNKNOWN) as to whether the number is known to be a live connected number. This service does not do actual connection testing, but certain contact types are virtually guaranteed to be connected. RecommendConnectionCheck is a ServiceObjects recommendation (TRUE, FALSE or RISKY) for further testing on a particular number to determine if it is actually connected. Generally true disconnected testing on wireless numbers is unreliable so most wireless numbers are marked as RISKY. ServiceObjects has a few options for working with disconnected numbers and is working on more.

GetPhoneInfo_V2 Inputs

GetPhoneInfo_V2 Outputs

Errors

Anything that happens during a run of DOTS GeoPhone Plus that causes it to be unable to finish its normal processing is an error. If an error occurs, something like the following will be the result instead of the normal output:
Example:

There are four error types described below. For DOTS GeoPhone Plus, the first two will be the most common.

Error Types

Error type 1: Authorization

These are standard to all Generation 2 DOTS Web Services.

Error type 2: User Input

These errors occur as a result of bad input. DOTS GeoPhone Plus requires all three inputs to be present in order for a proper validation to take place.

Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either a bug in the DOTS GeoPhone Plus service, or a Network/Connectivity issue.

Error type 4: Domain Specific

Domain specific errors represent the normal errors seen in ServiceObjects services. For example, if the user is looking for an address in DOTS Address Validation and the address does not exist, a valid domain specific error is “Address not found.”

Frequently Asked Questions

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses.

The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to:
https://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx

Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn’t able to connect, either. Contact your systems administrator to resolve why you are not able to connect to Service Objects.

GeoPhone Plus doesn’t find any data for my phone number!

If your phone number is unlisted, by law, it cannot find any contact information for your number. Additionally, if your number is for a cellular phone, it cannot find that contact information either. If it does not return any information for the exchange, then you may have mistyped your phone number. A valid phone number will always return exchange information, whether it is wireless or landline, connected or disconnected.

GeoPhone Plus is giving someone else’s information for my phone number!

GeoPhone Plus’s data is updated constantly. In the case that you just changed your number, it is possible it has not been updated since you made the change. Occasionally phone companies take their time in publishing updates.
If the information is not accurate, and the given phone number has not recently changed ownership, please let us know at support@serviceobjects.com.

Can GeoPhone Plus give me the information for a disconnected number?

No, although we are working on procuring this information. If you are interested in using this data, please contact us at support@serviceobjects.com, and we will let you know when that has been implemented.

Can GeoPhone Plus give me the information for a Canadian phone number?

Yes – normally. Our dataset for Canada isn’t as extensive as our dataset for the US, but GeoPhone Plus returns information for Canadian phone numbers.

I’m seeing multiple contacts at a single phone number. Who is really going to pick up the phone?

Honestly, any one of them! Typically, this means that multiple people are registered to that phone number, which happens with many small businesses. Oftentimes, when you call the number, you will get an operator or switch where you can ask for the person you’re looking for. If the phone number resolves to a residential address, all of the contacts may be roommates.
If you need to verify that a particular person is at that phone number, simply search for that person in the list of contacts. They are not in any particular order when they are returned.

What does the Quality flag in the contact output mean?

The Quality flag in the contact was designed as a placeholder for identifying lower quality data sets. In the event that Service Objects obtained useful but less reliable phone contact information this flag would be used to identify these new data sources. For now all Landline numbers come back as HIGH Quality and wireless numbers come back as UNKNOWN (due to the current state of wireless data in general). There are no plans to add new lower quality data sources to Geophone Plus at the moment and its likely new data sources would lead to a new operation version or require a special test type to access (eliminating the risk of getting lower quality data by accident).

What are tokens?

See Appendix A for more details on tokens.

I don’t care so much about who is at the phone number. I care more about whether the phone number is real or not. What should I do?

You have several options. You can either check for the presence of exchange data (valid phone numbers always return exchange information) or integrate Service Objects’ PhoneExchange web service, which was built expressly for this purpose. Find out more about PhoneExchange here: https://www.serviceobjects.com/phone-insight/?phone-exchange

I’m Not a Programmer. How Do I Use DOTS GeoPhone Plus?

Service Objects runs batches for you! A free batch trial is available at https://www.serviceobjects.com/upload-center/.

More Information

Appendix A – Tokens: An Advanced Feature

The standard usage and pricing plan for use of DOTS Geophone Plus is based on transactions as the aggregated and charged for unit. Transactions in this context are defined as: any DOTS Geophone Plus procedure call made to Service Objects web service, regardless of returned information or use of returned information. There is an advanced feature of DOTS Geophone Plus for more sophisticated users called Tokens. A Token is a unit of cost where different results are weighted differently resulting in a variable cost per transaction type. Transactions pricing is therefore variable and the plan is based on purchasing an amount of Tokens per month rather than Transactions. If a user desires closer accounting and measurement of specific Procedures used by their application and a payment plan that reflects this through variable pricing then the use of Tokens may provide added value. The Token cost structure is listed in the following table.

Conclusion

ServiceObjects is proud to offer you a free trial of DOTS GeoPhone Plus.

Sign up today for a free trial at:
https://www.serviceobjects.com/phone-insight/

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS GeoPhone Plus, please contact sales@serviceobjects.com.

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com