Data Partner Integration API Specification

Skip to end of metadata
Go to start of metadata

Document Info

Contact Information

Back To Contents

Company Address Business Contacts Technical Contacts
All Web Leads, Inc.
7300 FM 2222
Bldg 2 Ste 100
Austin, TX 78730
Office: 888-522-7355
J.R. Attick
Vice President, Sales 
jeremy.attick@allwebleads.com
Office: 512-279-3115 
Mobile: 512-826-1420 
Kenneth Armond
Software Engineer
PartnerIntegrations@allwebleads.com

Revision History

Back To Contents

Date Rev. Comments
7/9/2013 1.0 New version of document specific to V1.5 API
8/5/2013 1.1 Updated schema since new fields were added. Updated carrier name list.
12/3/2013 1.2 Added TcpaCompliant element under LeadMetaData node.
3/27/2015 1.3 Added Dynamic Calls Ping Response section with schema and sample rejection responses.

Introduction

Back To Contents

This document details the set of technical requirements expected to be met by any potential Data Partner interested in purchasing leads from All Web Leads, Inc. (referred to hereafter as AWL).

Data Partners are defined as those business partners that receive complete Lead Data directly via partner-hosted web services.

This document assumes that AWL Data Partners provide a web service implementation within their own data center environments that is available over the internet. AWL will consume the implementation of that web service, according to a provided specification, allowing AWL to post complete leads including all associated data to the partner.

AWL Lead Request and Response XML Schemas

If the Data Partner does not already have their own lead specification, they are encouraged to use the AWL Lead Type XML Schema and the AWL Lead Response XML Schema. The field value mappings are within the Lead Type XML Schema with the exception of the Insurance Carrier mappings.
A list of sample response codes/descriptions are available in section 2.5.1 of this document.

Here are lead samples of our most common lead types.

Dynamic Call Ping

Dynamic Call Partners are typically set up as ping/post integrations. AWL pings the partner the lead data without PII (Personally identifiable information). If the partner has call transfer offers for this lead, they respond to the ping with one or more call transfer offers along with the price and other necessary information for each call transfer offer. Otherwise, the ping is rejected and a rejection response containing a rejection reason is sent.

Call Transfer Offers

Call transfer offers in the ping response require certain fields and also have some optional fields to support different customer set ups. The ping response can contain multiple offers for a single call and all offers will be considered in the call auction as long as the highest offer price meets the floor price set on the account.

Ping response attributes:

Attribute name Is required? Description
Session ID Yes Unique ID associated with the ping
Call ID Yes Unique ID associated with the call offer
Bid Price Yes Proposed offer price for the call transfer
Carrier Name Maybe The carrier name associated with the offer. If carrier is not available or does not map to our carrier list* then the agent license number is required.
Agent License_number Maybe The agent license number associated with the offer. If the license number is not available, then a carrier from our carrier list* is required.
Transfer Phone Number No The phone number to transfer the call to. If this is not available then the static phone number set up on the account is used.
Transfer Phone Number Extension No The phone number extension should be in a separate field (not together with the phone number) in the ping response if used. The extension must go directly to a human agent, not an IVR. (Note: Only supported for warm transfers. Not supported on cold transfers)
Transfer Agent First Name No The first name of the agent that is receiving the call on the customer's end.
Transfer Agent Last Name No The last name of the agent that is receiving the call on the customer's end.

* We will map our carrier name list with the customer's carrier list.

Sample Ping Response Setup

Dynamic Call Ping Response Schema

A list of sample response codes/descriptions are available in section 2.5.1 of this document.
Here are some sample dynamic call ping responses.

Dynamic Call Post

The data post associated with the call transfer that contains the full lead data (including PII). In a ping/post setup, a successful ping response is required before the post. The customer account must be chosen in our live call auction before the post can occur. If the customer account is set up to receive the full lead data, our system will post this data to the customer's API right before the call is transferred to the agent.

Key Requirements

Protocol Requirements

Back To Contents

AWL requires Data Partners to provide access to an HTTP-based web service that allows AWL to transmit lead data.
AWL systems can support web services supporting secure HTTP POST.

Security Requirements

Back To Contents

AWL imposes at basic set of security requirements upon all Data Partners that receive complete Lead Data from AWL. These security requirements are intended to provide identity and personal information privacy for all end-consumer contacts contained within any lead. These security requirements are also intended to provide basic liability protections for AWL as well as its Data Partners.

Web Service Transport Security

AWL requires that all Data Partner web service implementations utilize industry-standard SSL/TLS over HTTP (HTTPS) as a transport mechanism. HTTPS provides authentication, message confidentiality, and message integrity at the transport level.

Data Partner web services should require some form of authentication to ensure that the web services are only accessible by trusted partners. Standard HTTP Basic or Digest authentication should be used, or alternatively, a custom authentication mechanism such as involving a token or password sent with the posted data.

Data Partner Security

AWL requires that all Data Partners provide their own measures to ensure that all lead data is received, stored and maintained in a secure manner and environment.

Additionally, any downstream transmission of received lead data must also be performed in a secure fashion to ensure the security of the lead throughout its entire lifecycle.

Quality of Service Requirements

Back To Contents

Reliability and Availability Requirements

AWL mandates a basic set of requirements related to quality of service intended to ensure that service requests from AWL to its Data Partners may be transmitted successfully and accurately.

It is expected that the Data Partner web service is available 24 hours a day, 7 days per week.

Any routine or regular maintenance should be communicated well in advance to the appropriate AWL technical personnel (operations@allwebleads.com), allowing for the necessary coordination to ensure an appropriate level of service.

Idempotence and Duplicate Detection Requirements

The term idempotence describes the property of operations in computer science which yield the same result after an operation is applied multiple times.

In the case of an AWL Data Partner web service, the web service must ensure idempotence by providing the same result in the event that a transaction contains duplicate data received from a previously successful transaction.

For instance, it is possible that AWL sends a lead which is successfully stored in the Data Partner system, but before the AWL system receives a success acknowledgement, which can occur if the underlying connection is closed. Ideally, the Data Partner web service would completely rollback the transaction, however it is understood that this is not possible in all scenarios. In such a situation, AWL will attempt to retry the transaction by posting the exact same lead data a second time. The Data Partner web service should return a success code in this case, because the lead was previously successfully received, so it should return an identical result.

AWL makes every effort to refrain from posting the exact same lead data multiple times to the same Data Partner; however, the inherent nature of distributed inter-operable systems renders any guarantee of duplicate posts impossible.

It is critical that Data Partner web services differentiate between duplicate leads from the same partner (which are not really duplicates, but rather re-tries), and duplicate leads from different partners, which are true duplicates.

Timeout and Retry Requirements

AWL ensures reliability of the system by utilizing transaction timeouts and a basic retry mechanism for failed or timed out transactions. In the event that AWL experiences an unacceptable latency during any given transaction, that transaction will be timed out, and, after a short delay, AWL will attempt to retry the exact same transaction a number of times.

It is the responsibility of the AWL Data Partner web service to detect a cancelled transaction due to a timeout and ensure that no lead data is stored whatsoever (rollback), and the web service must be prepared to receive the exact same data successfully on a subsequent retry attempt.

If for any reason a failed (but not timed-out) transaction attempt should not be retried, the Data Partner web service should return the standard HTTP status code of 503 to indicate that the web service is temporarily unavailable, which will inform the AWL systems that a retry is not appropriate at the current moment. Otherwise, the AWL systems will perform a retry.

Performance Requirements

Back To Contents

Web Service Latency

AWL records and closely monitors the latency, in seconds, of every post to a Data Partner web service. AWL requires that all Data Partner web services respond with either a success or failure result in the shortest amount of time possible.

Most AWL Data Partner web services have an average latency in the 2 to 5 second range. Obviously, external factors are always at play on the open internet and latency values are expected to fluctuate; however, it is important that average latency remains within a reasonable time range.

Low web service posting latency is critical to ensure timely processing and routing of the leads, and benefits all involved partners (consumer, AWL and the Data Partner).

Simultaneous Requests

To ensure the most expedient routing and delivery of leads, the AWL systems may route leads in a multi-threaded (simultaneous) fashion. This means that AWL expects all Data Partner web services to support accepting multiple leads in a simultaneous fashion.

It is required that Data Partner web services support receiving multiple leads in a manner that is independent and isolated for each individual lead post.

If for any reason a failed (but not timed-out) transaction attempt should not be retried, the Data Partner web service should return the standard HTTP status code of 503 to indicate that the web service is temporarily unavailable, which will inform the AWL systems that a retry is not appropriate at the current moment.

Result Code and Acknowledgement Requirements

Back To Contents

AWL requests that any Data Partner web service implementation supports returning a rich set of result codes to communicate as much information as possible.

Result codes may be returned as a string data type, an integer data type, or both for the easiest diagnostic capability. In addition to any associated result codes, any error should ideally be accompanied by a human-readable and helpful description of the exact reason the failure occurred.

If the Data Partner associates an internal-only unique identifier to the lead upon successful insertion, the result should include the Data Partner’s assigned lead identifier. This helps with diagnostics and correlation of lead data between AWL and its Data Partners.

Any Data Partner-specific result codes should be clearly communicated in the form a specification to AWL so that the AWL systems may handle those partner-specific conditions as appropriately as possible.

Please refer to the following section for detailed information on the recommended set of result codes that the AWL systems expect to receive from Data Partner web services.

Example Result Codes
String Code Numeric Result Code Description
NO_ERROR 0 Success
UNKNOWN_ERROR 3 An unknown error occurred within the web service
DUPLICATE_ERROR 4 Duplicate lead, either successfully received already from AWL or from another third-party partner also consuming the web service
CONTENT_ERROR 5 Lead was successfully received and parsed, but there was a generic or internally specific problem with the content of the data
INVALID_POST 6 Lead data was received, but there was problem in parsing the data
INVALID_PHONE 7 A required phone number was missing or otherwise invalid
INVALID_ZIP 8 The zip code was missing or otherwise invalid
NO_AVAILABLE_MATCH 9 Lead data was received, but could not be matched appropriately
INVALID_XML 10 A generic XML parsing error for web services that accept data in XML format
SCHEMA_VALIDATION_ERROR 11 A generic XML schema validation error for web services that accept data in XML format and provide an XML schema for validation
PARTNER_DATA_ERROR 12 Lead was successfully received and parsed, but there was a generic or internally specific problem with the content of the data
PRODUCT_TYPE_ERROR 13 Lead was successfully received and parsed, but the type of lead is not supported (implies a filtering problem in AWL system)
INVALID_GEOGRAPHY 14 Lead was successfully received and parsed, but was associated with an invalid geographic region (implies a filtering problem in AWL system)
UNINSURABLE 15 Lead was successfully received and parsed, but was associated with an uninsurable contact (implies a filtering problem in AWL system)
INVALID_EMAIL 16 The primary contact email address was missing or otherwise invalid
MISSING_FIELDS 17 Lead was successfully received and parsed, but required fields were missing (should be used for fields that don’t have unique result codes, or when multiple required fields are missing)
INVALID_DOB 18 A specified contact date of birth was missing or invalid
INVALID_NAME 19 A specified contact name was missing or invalid
INVALID_ADDRESS 20 Primary contact address is missing or invalid
INVALID_AGE 21 A specified contact is of an invalid age (implies a filtering problem in AWL system)
PARTNER_PAUSED_LEADFLOW 54 Data Partner paused incoming lead flow in their system
INVALID_CREDENTIALS 64 Incorrect username and/or password on lead post
FAILED_PARTNER_LEAD_DATA_VALIDATION 65 Failed the Data Partner’s lead validation
EMAIL_SUPPRESSED 70 Missing email address
INVALID_VIN 73 Invalid Vehicle Identification Number (Auto leads)
SCORING_MODEL_REJECTION 84 Lead does not meet the minimum value on the Data Partner’s scoring model

Versioning Requirements

Back To Contents

AWL expects all Data Partner web services to be versioned in an appropriate manner allowing for reliable interoperability. This means that any changes to the Data Partner web service should be coordinated with the AWL technical team. AWL is happy to assist in any way, and to perform the necessary testing to ensure that any upgraded web service will result in the least amount of service disruption as possible (see Testing Requirements).

Testing Requirements

Back To Contents

To ensure a smooth and successful integration, AWL highly recommends that Data Partner web services provide a means by which testing can be performed prior to any production-level integration deployment.

AWL strongly recommends that Data Partners provide a parallel testing environment of some kind. This testing environment should provide an endpoint (web service address) that is unique from the production environment endpoint. The testing environment should also guarantee a clean separation between test leads and production leads such that no risk exists of test leads inadvertently being used in a production manner.

The testing environment should also provide flexible configuration options that ease the testing efforts, such as the ability to ignore potential duplicates for testing purposes, and to temporarily disable certain validation mechanisms. These mechanisms are not expected to be exposed to AWL directly, but are expected to be present when AWL and the Data Partner are coordinating any testing effort.

A testing environment is an important aspect to ensuring a smooth and successful initial integration, as well as to ensure successful upgrades and enhancements to the integration in the future.

Reporting Requirements

Back To Contents

To ensure accurate results, AWL recommends that all Data Partners provide a web-based user interface by which AWL personnel may log in and receive basic reports regarding the status of leads successfully posted to the Data Partner web service.

Reporting requirements are defined in a separate document. Please contact AWL for the latest copy of this document.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.