- 1 Document Info
- 1.1 Contact Information
- 1.2 Revision History
- 1.3 Introduction
- 1.4 AWL Lead Request and Response XML Schemas
- 1.5 Dynamic Call Ping
- 1.6 Dynamic Call Post
- 2 Key Requirements
- 2.1 Protocol Requirements
- 2.2 Security Requirements
- 2.3 Quality of Service Requirements
- 2.4 Performance Requirements
- 2.5 Result Code and Acknowledgement Requirements
- 18.104.22.168 Example Result Codes
- 2.6 Versioning Requirements
- 2.7 Testing Requirements
- 2.8 Reporting Requirements
|Company Address||Business Contacts||Technical Contacts|
| All Web Leads, Inc.
7300 FM 2222
Bldg 2 Ste 100
Austin, TX 78730
| J.R. Attick
Vice President, Sales
| Kenneth Armond
|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.|
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.
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.
- Sample Auto Lead
- Sample Home Lead
- Sample Health Lead
- Sample Life Lead
- Sample Renter Lead
- Sample Annuity Lead
- Sample Business Property Lead
- Sample Disability Lead
- Sample LTC Lead
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 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||Yes||The phone number to transfer the call to.|
|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.|
|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.
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.
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.
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.
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.
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.
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.
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 (firstname.lastname@example.org), allowing for the necessary coordination to ensure an appropriate level of service.
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.
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.
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).
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.
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.
|String Code||Numeric Result Code||Description|
|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|
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).
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.
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.