- Introduction
- Integration
- Web Service Structure
- Operation Definitions
- Error Codes
- Frequently Asked Questions
- Conclusion
Introduction
DOTS PhoneAppend (referred to as “PhoneAppend” or “PA”) is a publicly available XML web service that provides phone lookup information about U.S. and Canadian contacts. The service will search by name, address, city, state (or province), and postal code to find a listed phone number.
PhoneAppend provides instant phone lookup and verification to websites or data enhancement to contact lists.
Integration
Integrating PhoneAppend 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=69
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 complicated business logic. Web services are too large of a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible.
PhoneAppend is a public XML web service that is accessed via SOAP, HTTP POST and HTTP GET protocols.
The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/pa/PhoneAppend.asmx
The location of the WSDL, or Web Service Definition Language document, is here (The WSDL is also accessible via the “Service Definition” link from the host path.):
https://trial.serviceobjects.com/pa/PhoneAppend.asmx?WSDL
Important Note!
SOAP is done via HTTP POST with special XML markup in the post-body.
The WSDL is the definition of the web service, defining its inputs, outputs, operations, and nontrivial data types. Most likely, you will have a tool for your programming language read the WSDL and generate operations for your application. When your utilities or IDE asks for a WSDL path to PhoneAppend, you provide the host path.
Every web service has operations that it offers to subscribers – methods that do different work and return different output. Examining the link above, you will notice several operations, which are described in detail later.
GetPhoneAppend – given a person’s name, address, city, state (province), and postal code, will return the contact’s phone number (if listed).
GetBusinessPhoneAppend – like GetPhoneInfo, but emphasized for businesses. If you have a business name, address, city, state (province), and postal code, use this operation instead of GetPhoneInfo. (Deprecated: Use GetBusinessPhoneAppend_V2)
GetBusinessPhoneAppend_V2 – like GetBusinessPhoneAppend, but returns additional information beyond the phone number. The V2 (“version 2”) operation returns the business name, address, city, state (province), and postal code in addition to the phone number. (Recommended operation)
Each of these operations will be described in detail later in this document.
Operation Definitions
This document defines the input, output and behavior of the web service operations in PhoneAppend. Each operation has its own unique behavior and output, although all of the operations are very similar.
Important Note!
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.
PhoneAppend returns contact information for connected landline phone numbers. Even in the cases that the phone number is disconnected or wireless, PhoneAppend will commonly return the exchange information. PhoneAppend provides contact information regarding Canadian phone numbers, although PhoneAppend Canadian data is not quite as comprehensive as its US information.
You should examine your own business needs first before exploring what PhoneAppend can provide. Different operations may be necessary based on the information you have, and the granularity of data you need.
GetPhoneAppend
This is the basic operation for finding residential lookup information. Given a contact’s information, PhoneAppend will consult national directory-assistance databases to find the owner and registered phone number.
GetPhoneInfo Inputs
| Input Name | Type | Description |
|---|---|---|
| FirstName | String | First name of contact |
| LastName | String | Last name of contact |
| Address | String | Address1 of contact (address2, such as unit number, is unnecessary) |
| City | String | City of contact |
| State | String | State of contact |
| Zip | String | Zip of contact (city/state or zip is required) |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at www.serviceobjects.com. |
GetPhoneInfo Outputs
| Output Name | Type | Values | Description |
|---|---|---|---|
| Phone | String | Varies | Phone number for contact, always formatted as: “(NPA) NXX-ZZZZ” |
| Error – Desc | String | Varies | If there was an internal web service error, the description will be displayed here. |
| Error – Number | String | “1”, “2”, “4” | See “Error Codes” below. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetBusinessPhoneAppend
This operation is almost exactly like GetPhoneAppend, but emphasizes business contacts.
GetBusinessPhoneAppend Inputs
| Input Name | Type | Description |
|---|---|---|
| Business | String | Business name |
| Address | String | Address1 of business (address2, such as unit number, is unnecessary) |
| City | String | City of business |
| State | String | State of business |
| Zip | String | Zip of business (city/state or zip is required) |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at www.serviceobjects.com. |
GetBusinessPhoneAppend Outputs
| Output Name | Type | Values | Description |
|---|---|---|---|
| Phone | String | Varies | Phone number for business, always formatted as: “(NPA) NXX-ZZZZ” |
| Error – Desc | String | Varies | If there was an internal web service error, the description will be displayed here. |
| Error – Number | String | “1”, “2”, “4” | See “Error Codes” below. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetBusinessPhoneAppend_V2
This operation is almost exactly like GetBusinessPhoneAppend, but additionally returns the business name, address, city, state (province), and postal code. This additional information can be used to clean your database, and ensure that the returned information is for the intended business.
GetBusinessPhoneAppend_V2 Inputs
| Input Name | Type | Description |
|---|---|---|
| Business | String | Business name |
| Address | String | Address1 of business (address2, such as unit number, is unnecessary) |
| City | String | City of business |
| State | String | State of business |
| Zip | String | Zip of business (city/state or zip is required) |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at www.serviceobjects.com. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at www.serviceobjects.com. |
GetBusinessPhoneAppend_V2 Outputs
| Output Name | Type | Values | Description |
|---|---|---|---|
| Name | String | Varies | The business name that the phone line is registered to. |
| 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 |
| Debug | String | Varies | Usually an empty string, but may be used to output helpful information as necessary. |
| Error – Desc | String | Varies | If there was an internal web service error, the description will be displayed here. |
| Error – Number | String | “1”, “2”, “4” | See “Error Codes” below. |
| Error – Location | String | Always null | Deprecated, no longer used. |
Error Codes
Error codes in PhoneAppend are the same for all operations. They are as follows:
Error Code 1 – “Input cannot be less than zero length”
This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand. This error often happens when input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (Email or LicenseKey, in this service) will cause this error. Additionally, requests made in the “rpc/encoded” format will cause this error. The only namespace that should appear in any element is the “https://www.serviceobjects.com” namespace on the root ValidateEmail element as so:
<GetPhoneAppend xmlns="https://www.serviceobjects.com/">
Note, however, that the namespace is not applied to the GetPhoneAppend element, it is only present.
Error Code 2 – Various descriptions
This error code appears when various errors occur, but are of the expected nature. The most common occurrence is when there is no business contact listing found. Additionally, maligned or incomplete input will cause an error 2. Again, check the Error’s Desc element for the exact error.
Error Code 4 – Various descriptions
An error code 4 is a fatal error and it means something has seriously gone wrong. You should never see an error code 4 in a live production environment.
Frequently Asked Questions
Why are there operations that end with a V2?
When we need to enhance our service that includes the changing of either the input or output interfaces, its best to create a new operation. If we change the interface of an existing operation, we potentially adversely affect hundreds of current customers.
If you are a new client or in a position to make a change, its usually always best to switch to the new operation as it likely has important new enhancements.
The Sample Code is Giving Strange Errors or is Crashing!
Most likely, the sample code cannot connect to ServiceObjects. 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/pa/PhoneAppend.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 ServiceObjects.
PhoneAppend doesn’t find any data for my information!
If your phone number is unlisted, by law, it cannot be found by searching by contact information. Additionally, if your number is for a cellular phone, PhoneAppend cannot find your information. 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.
PhoneAppend is giving someone else’s phone number for my information!
PhoneAppend’s data is updated constantly. In the case that you just changed your number, it probably just has not been updated since you made the change. Sometimes 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 PhoneAppend 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 PhoneAppend give me the information for a cell phone or wireless number?
No. This information was somewhat restricted until recently, and even those databases that are currently available do not cover every wireless number in the US. We are also in the process of procuring this information, and will keep you updated if you are interested.
Can PhoneAppend give me the information for a Canadian phone number?
Yes – sometimes. Our dataset for Canada isn’t as extensive as our dataset for the US, but PhoneAppend returns information for Canadian phone numbers.
I’m Not a Programmer. How Do I Use DOTS PhoneAppend?
ServiceObjects runs batches for you! A free batch trial is available at
https://www.serviceobjects.com/upload-center/.
Conclusion
ServiceObjects is proud to offer you a free trial of DOTS PhoneAppend US.
Sign up today for a free trial at:
https://www.serviceobjects.com/phone-insight/?phone-append
Other technical questions or concerns can be directed to support@serviceobjects.com.
If you are interested in purchasing DOTS PhoneAppend, 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