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

Andi Whittaker
Director, Customer Success  
andrea.whittaker@allwebleads.com 
Office: 512-942-6197  

Patrick Jean
Stephen Connolly
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

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.

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.


  • No labels