Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
_tocTop
_tocTop
 

Table of Contents
maxLevel3
outlinetrue
locationtop
stylenone
typelist

Document Info

Contact Information

Company Address

Business Contacts

All Web Leads, Inc.
7801 Capital of Texas Highway
Suite 220
Austin, TX 78731-1171
Office: 888-522-7355

Jamie Oliver
Director, Strategic Alliances
jamie.oliver@allwebleads.com
Office: 512-279-3093
Mobile: 512-983-2303

...

Date

Rev.

Comments

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7f467fa99d2d084c-e4fa3884-4aae4d0c-9f1a91d1-f2fe9853b8a4bfc306ae7760"><ac:plain-text-body><![CDATA[

3/21/2011

4.0

New version of document specific to V4.0 API, based on [original V3.0 API document

http://extranet.allwebleads.com/display/ENG/Partner+Specification+Portal#PartnerSpecificationPortal-Version3.0API] [JDR]

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="17cd6afd96fbfbd3-b6df3b23-483f-ad82b786-ed42b9c5e1d692eb0c004829"><ac:plain-text-body><![CDATA[

4/7/2011

4.1

Updated staging test application information. Added clarification that the actual web service endpoints do not support HTTPS GET protocol. [JDR]

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c9690c7d225c52cc-db9b52db-45a740bf-be768f56-3d7eccede74188ab2a3f5cc3"><ac:plain-text-body><![CDATA[

4/13/2011

4.2

Updated for new Health Insurance and Home Insurance support, as well as Undersold support [JDR]

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="ae3745163ee1d111-d31f07a7-48154f9a-8293ba4a-7422fff66a22ef24258d0bf0"><ac:plain-text-body><![CDATA[

4/25/2011

4.3

Moved document to the AWL extranet wiki [JDR]

]]></ac:plain-text-body></ac:structured-macro>

 

 

 

 

 

 

Table of Contents

...

...

outlinetrue
locationtop
stylenone
typelist

Introduction

Back To Contents

This document details the information necessary for Data Affiliate partners to begin selling leads to All Web Leads, Inc. (referred to hereafter as AWL) via the AWL Version 4.0 Data Affiliate web service API.

Data Affiliates are defined as those business partners that offer complete Lead Data for purchase to AWL by means of a real time web service provided by AWL.

The AWL Version 4.0 API replaces the previous Version 3.0 API. All partners are encouraged to integrate with the Version 4.0 API, as the 3.0 API will slowly be phased out and discontinued early in 2012.

The Version 4.0 API is intended to be an evolutionary step from the non-SOAP capabilities of the 3.0 API. The primary difference between the V4.0 API and the V3.0 API is that the SOAP-based web services are no longer support, and the V4.0 API relies on entirely new Lead definitions (new lead XML Schema, included along with this specification document).

Supported Features

Back To Contents

Lead Types

Back To Contents

Currently, the Version 4.0 API only supports the following insurance lead types:

  • Auto
  • Life
  • Health
  • Homeowners

Lead Subtypes

Back To Contents

In addition to the above lead types, a more detailed categorization, or "Lead Subtype", is also supported. Lead Subtypes are commonly used to define payout and daily lead limit information associated with each Data Affiliate account. Note that not all Lead Types have associated Lead Subtypes.

Auto

Back To Contents

  • Premium Auto
    • Require 1 Driver 22 or Older
    • Require all drivers currently insured
    • Require all drivers have valid licenses /no license suspension (meaning ACTIVE and TEMPORARY is OK)
    • Require NO SR-22
    • Require NO DUI/DWI
    • Require One or Less Tickets
    • Require NO Major Violations (meaning no DUI, and no careless driving)
    • Require No At Fault Accidents
      • Note that if the user selects that an accident is not at-fault, but then selects "Your Vehicle Hit Other Vehicle", we treat that accident as an at-fault accident
  • Standard Auto
    • Require 1 Driver 18 or Older
    • Require all drivers currently insured
    • Require all drivers have valid licenses/no license suspension
    • Require NO SR-22
    • Require NO DUI/DWI
    • Require Three or Less Tickets
    • Require One or Less At Fault Accidents
  • Substandard Auto
    • Require 1 Driver 18 or Older
    • Anything not meeting Premium or Standard risk
  • Juvenile Auto
    • All drivers under age 18

Life

Back To Contents

  • Premium Life
    • Applicant age 35 - 60
  • Standard Life
    • Applicant age 25 - 34
  • Substandard Life
    • Others

Health

Back To Contents

  • Standard Health
    • 1 applicant age 64 or younger
    • No Pregnancy
    • BMI Less than or equal to 35
    • No Major health conditions
    • No Diabetes
    • No Kidney disease
  • Substandard Health
    • 1 applicant age 64 or younger
    • Anything not meeting Standard Health criteria
  • Senior Health
    • All applicants age 65 or older

Exclusive and Undersold (Shared) Leads

Back To Contents

The Version 4.0 API currently allows AWL to purchase/accept exclusive leads from its Data Affiliate partners, as well as Undersold (shared) leads that provide distribution directives indicating how the lead has already been sold by the offering Data Affiliate partner.

Account Lead Limits

Back To Contents

The AWL system allows AWL account managers to specify limits (e.g. daily lead limits) on inbound lead volume. If a partner attempts to send leads into the AWL system and the partner account has already exceeded a configured lead limit cap, the lead will be rejected.

With the AWL price presentation ping-post APIs, lead limits are checked during the ping, and also on a subsequent post. This can result in the AWL system accepting and returning a non-zero price for a ping, but then rejecting the subsequent post if the partner lead limit has been hit after the successful ping but prior to the subsequent post. This should be a rare occurrence, and should only occur temporarily at the partner's lead limit boundary point. The frequency with which this will happen is also highly dependent upon the partner's inbound rate of pings and posts, and the concurrency of those transactions into the AWL system.

Duplicate Detection

Back To Contents

The Version 4.0 API will reject leads that are determined to be a "duplicate" within our system. When a lead is determined to be a duplicate, it is rejected with a discrete error code.

Our system identifies duplicates by comparing an incoming lead's primary application contact information with leads already in our system. Specifically, we compare based on email address, daytime phone number, and street address, and only compare against leads of the same lead type (Health, Auto, etc.), and only perform this comparison on leads created within our system within the past 30 days.

Note that the AWL system performs duplicate detection on all incoming leads where personally identifying information is provided. For inbound lead pings where personally identifying information is not provided, it is possible for the AWL system to return a non-zero ping price, but then determine that the lead is a duplicate on a subsequent inbound post of the same lead.

Note that the AWL system makes every effort to accurately 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. For more information, please refer to the section entitled "Idempotence and Duplicate Detection" later in this document.

Technical Overview

Back To Contents

Protocol

Back To Contents

The AWL API is available as a simple HTTP POST API, exposed over SSL. This API can be consumed by almost any HTTP client technology.

Security

Back To Contents

The AWL Data Affiliate API provides a very simple security infrastructure.

Transport Security

Back To Contents

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

Authentication

Back To Contents

All Data Affiliates will be assigned a unique affiliate identifier, an affiliate username, and a password. The identifier is used internally to uniquely identify the partner, while the affiliate username and password must be provided in each API call in order to allow AWL to ensure the source of the incoming lead.

Firewall Restriction

Back To Contents

Access to the AWL Data Affiliates API is firewall-restricted. Data Affiliate partners must provide an IP address or an IP address range in order for AWL to white-list access. Note that both staging and production IP addresses will be required.

Quality of Service

Back To Contents

Reliability and Availability

Back To Contents

AWL makes every effort to ensure that the API is available 24 hours a day, 7 days per week so that services requests from Data Affiliate partners to AWL may be transmitted successfully and accurately.

Realistically, some level of downtime will be required to allow for routine maintenance. A regular maintenance window occurs on Sundays between 12:00am and 2:00am. Any necessary downtime outside of that window will be communicated ahead-of-time to the appropriate parties, and every effort will be made to provide adequate notice.

When the AWL API is unavailable due to routine maintenance, any API calls will experience a standard HTTP response of 503 (Service Unavailable).

For any problems encountered by partners that do not appear to be associated with routine maintenance, the appropriate AWL technical personnel can be contacted via our "operations" email list: operations@allwebleads.com.

Idempotence and Duplicate Detection

Back To Contents

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 the AWL Data Affiliates web service, the web service ensures 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 a partner sends a lead which is successfully stored in the AWL system, but before the partner system receives a success acknowledgement. This can occur if the underlying connection is closed. Ideally, the AWL system would detect the closed connection and therefore understand that it cannot return a success acknowledgement to the partner client, however it is understood that this is not possible in all scenarios. In such a situation, AWL requires the partner to attempt to retry the transaction by posting the exact same lead data a second time. The AWL system will return a success code in this case, because the lead was previously successfully received, so it should return an identical result.

Data Affiliate partners should make every effort to refrain from posting the exact same lead data multiple times; however, we understand that the inherent nature of distributed interoperable systems renders any guarantee of duplicate posts impossible.

Note that the AWL system makes every effort to accurately 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 Retries

Back To Contents

AWL expects Data Affiliate partners to ensure reliability within their systems by utilizing transaction timeouts and a retry mechanism for failed or timed out transactions. In the event that the partner experiences an unacceptable latency during any given transaction with the AWL API, the partner should timeout that transaction, and, after a short delay, attempt to retry the exact same transaction. The AWL system is designed to expect partners to retry failed transactions.

If for any reason a failed (but not timed-out) transaction attempt should not be retried by the partner, the AWL system will 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.

Performance

Back To Contents

Web Service Latency

Back To Contents

AWL records and closely monitors the latency, in seconds, of every post to its system. AWL makes every attempt to return either a success or failure result in the shortest amount of time possible.

AWL single-lead post latencies average about 3 to 10 seconds. In a worst-case scenario, latencies may be as high as 60 seconds. Obviously, external factors are always at play on the open internet and latency values are expected to fluctuate; however, we realize it is important that average latency remains within a reasonable time range.

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

Simultaneous Requests

Back To Contents

To ensure the most expedient acceptance and routing of leads, the AWL systems accept leads in a multi-threaded (simultaneous) fashion, either from multiple Data Affiliate partners or from one partner.

The AWL system supports 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 AWL system will 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 Acknowledgements

Back To Contents

The AWL API supports returning a rich set of result codes to communicate as much information as possible in the event of a failure or rejection. Please see the detailed API specification information later in this document for specific information related to the supported set of result codes.

API Versioning

Back To Contents

AWL understands that partners invest time and effort into integrating with the AWL API. For this reason, AWL intends to maintain API backward compatibility as much as possible. From time to time, major version releases may break backwards compatibility with existing API consumers.

When it is necessary to break backwards compatibility with a new API version release, AWL intends to fully support the previous major version of the API for a period of up to 6 months, with the intent of providing adequate time for existing partners to migrate their client integrations.

At this time, AWL supports the previous Version 3.0 API and the new Version 4.0 API.

Web Service API Details

Back To Contents

The Version 4.0 API also supports a simple API mechanism consisting of an HTTP POST over HTTPS. This version of the API is supported by any standard HTTP client technology.

Data is passed to the HTTP POST API simply as UTF-8 encoded text, organized into ampersand-delimited key/value pairs representing a query-string-like syntax.

Send Lead Exclusive API

Back To Contents

The "Send Lead Exclusive" API is used to send leads to AWL for consideration for purchase. The lead must be provided in its entirety, including all personally identifiable information. The AWL system makes a real-time determination of whether or not to accept/purchase the lead based on a number of factors (see your account manager for details regarding your account configuration).

The "Send Lead Exclusive" API consists of the following URL:

https://<environment-base-url>/SendLeadExclusive

For example, in the AWL staging environment:

https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/SendLeadExclusive

A single post parameter is supported, which allows the passing of lead data in the AWL lead XML format:

  • XmlString (String)
    • An XML string containing the lead object. The XML string must conform to the AWL Lead XML V1.5 Schema (included with this documentation)
    • XML string must be in UTF-8 format and must NOT include a Unicode byte order mark (BOM)

Example HTTP POST Data Payload

Back To Contents

The following represents an example HTTP POST data payload for this API:

XmlString=<raw lead xml>

API Response

Back To Contents

The Send Lead Exclusive API generally will return a standard HTTP 200 response code to indicate a successful operation. Note, however, that a 200 response does not indicate that AWL has accepted the lead. The Data Affiliate partner must inspect the return value of the API to determine if AWL has elected to accept or reject the lead.

When an HTTP 200 response is returned, the return result consists of a UTF-8 encoded XML string. The XML returned conforms to the "LeadsUploadResult.xsd" XML schema document included along with this specification.

This schema contains a single XML type called "LeadsUploadResultType".

  • Result
    • Values:
      • "OK"
        • Indicates that the request was successfully processed
        • Only indicates that the lead was accepted/purchased in the event that a non-zero "Payout" value is returned
      • "ERROR"
        • Indicates that an error occurred during processing
  • ErrorType
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values:
      • "XML Validation"
      • "Data Validation"
      • "Login"
      • "Duplicate"
      • "Internal Server Error"
  • ErrorDescription
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values consist of a descriptive human-readable string. A few examples:
      • "Invalid Username/Password"
      • "XML Parse/Validation Failure"
      • "Re-post of identical lead from same partner"
      • "Unknown error occurred processing lead"
      • Etc.
  • Payout
    • Provided when the "Result" is "OK", and the AWL system has accepted/purchased the incoming lead
    • Represents the expected/estimated payout associated with the acceptance of an incoming lead by the AWL system
  • LeadID
    • Provided when the "Result" is "OK", and the "Payout" is greater than $0.00
    • The Lead ID within the AWL system, useful for diagnostic and tracking purposes
    • This value should be logged/recorded in each partner's system
  • DataFieldValidation
    • Provided when the "Result" is "ERROR". Zero or more "DataFieldValidation" nodes may be included indicate which field or fields triggered an error response.
    • DataField
      • Identifies the data field (element) within the Lead XML that triggered a validation error
      • Values:
        • nameFirst
        • nameLast
        • nameMiddle
        • namePrefix
        • nameSuffix
        • addressStreet
        • addressStreet2
        • city
        • state
        • zipCode
        • phoneDay
        • phoneEvening
        • email
        • currentlyInsured
        • insuranceProvider
        • lengthOfCoverage
        • coverageExpiration
    • DataFieldErrorType
      • Identifies the type of validation error that occurred
      • Values:
        • Fail
        • Warning
    • DataFieldErrorMessage
      • Provides additional information related to the validation error that occurred
      • May be empty when no additional information is available

Price Presentation Ping Lead API

Back To Contents

The "Price Presentation Ping Lead" API is used to send leads to the AWL system to receive a bid on the lead (this is often referred to as "price presentation ping-post" in the industry).

This API supports both Exclusive and Undersold (shared) lead buying. A lead presented with zero distribution directives is considered an Exclusive lead. A lead presented with one or more distribution directives is considered an Undersold lead.

The lead must be provided in its entirety, although all personally identifiable information for the primary applicant is considered optional. The AWL system evaluates the provided lead data based on a number of factors (see your account manager for details regarding your account configuration), and returns a price estimate constituting a bid on the lead.

When a non-zero price is returned, a "LeadID" value is returned which represents a ping session identifier. The ping session identifier may be used in a follow-up "Price Presentation Post Lead" API call to offer the lead for sale at the previously bid price point. Note that a lead bid price and its ping session identifier is valid only for up to five minutes.

The "Price Presentation Ping Lead" API consists of the following URL:

https://<environment-base-url>/PricePresentationPingLead

For example, in the AWL staging environment:

https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPingLead

A single post parameter is supported, which allows the passing of lead data in the AWL lead XML format:

  • XmlString (String)
    • An XML string containing the lead object. The XML string must conform to the AWL Lead XML V1.5 Schema (included with this documentation)
    • XML string must be in UTF-8 format and must NOT include a Unicode byte order mark (BOM)

Example HTTP POST Data Payload

Back To Contents

The following represents an example post data payload for this API:

XmlString=<raw lead xml>

API Response

Back To Contents

The Price Presentation Ping Lead API generally will return a standard HTTP 200 response code to indicate a successful operation. Note, however, that a 200 response does not indicate that AWL has placed a bid on the lead. The Data Affiliate partner must inspect the return value of the API to determine if AWL has indeed placed a bid on the lead.

When an HTTP 200 response is returned, the return result consists of a UTF-8 encoded XML string. The XML returned conforms to the "PricePresentationResult.xsd" XML schema document included along with this specification.

This schema contains a single XML type called "PricePresentationResultType".

  • Result
    • Values:
      • "OK"
        • Indicates that the request was successfully processed
        • Only indicates that the lead was bid upon in the event that a non-zero "Payout" and a valid "LeadID" value is returned
      • "ERROR"
        • Indicates that an error occurred during processing
  • ErrorType
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values:
      • "XML Validation"
      • "Data Validation"
      • "Login"
      • "Duplicate"
      • "Internal Server Error"
  • ErrorDescription
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values consist of a descriptive human-readable string. A few examples:
      • "Invalid Username/Password"
      • "XML Parse/Validation Failure"
      • "Re-post of identical lead from same partner"
      • "Unknown error occurred processing lead"
      • Etc.
  • Payout
    • Provided when the "Result" is "OK", and the AWL system has successfully placed a bid on the incoming lead
    • Represents the expected/estimated payout associated with a potential subsequent post of the same lead
  • LeadID
    • Provided when the "Result" is "OK", and the "Payout" is greater than $0.00
    • The Lead ID value is not a "real" lead identifier within the AWL system, but instead is actually a ping session identifier that must be used in a subsequent "Price Presentation Post Lead" API call if the partner chooses to offer the full lead to AWL for sale at the bid-upon price point
    • This value should be logged/recorded in each partner's system
  • DataFieldValidation
    • Provided when the "Result" is "ERROR". Zero or more "DataFieldValidation" nodes may be included indicate which field or fields triggered an error response.
    • DataField
      • Identifies the data field (element) within the Lead XML that triggered a validation error
      • Values:
        • nameFirst
        • nameLast
        • nameMiddle
        • namePrefix
        • nameSuffix
        • addressStreet
        • addressStreet2
        • city
        • state
        • zipCode
        • phoneDay
        • phoneEvening
        • email
        • currentlyInsured
        • insuranceProvider
        • lengthOfCoverage
        • coverageExpiration
    • DataFieldErrorType
      • Identifies the type of validation error that occurred
      • Values:
        • Fail
        • Warning
    • DataFieldErrorMessage
      • Provides additional information related to the validation error that occurred
      • May be empty when no additional information is available

Price Presentation Post Lead API

Back To Contents

The "Price Presentation Post Lead" API is used to offer leads to sale after those leads have successfully been bid upon by the AWL system via a previous call to the "Price Presentation Ping Lead" API.

This API supports both Exclusive and Undersold (shared) lead buying. A lead presented with zero distribution directives is considered an Exclusive lead. A lead presented with one or more distribution directives is considered an Undersold lead.

The lead must be provided in its entirety, including all personally identifiable information.

This API call must provide the "LeadID" value that was previously returned in a successful call to the "Price Presentation Ping Lead" API. This "LeadID" value represents a session identifier that associates the post with the ping. Note that a lead bid price and its ping session identifier is valid only for up to five minutes. If a call to this API uses a ping session identifier that is more than five (5) minutes old, that call will be rejected.

With the exception of the ping-time optional personally identifying information, the Lead XML provided in this post API must be identical to the XML presented earlier in the associated ping API. If the XML differs, the post will be rejected.

Prior to accepting the lead via this API, the personal identifying information will be validated. If the identifying information cannot be validated, the lead will rejected. Additionally, the personal identifying information will be used to determine if the lead is considered a duplicate within the AWL system. If the lead is a duplicate, it will be rejected (please refer to the "Duplicate Detection" section earlier in this document for additional details).

The "Price Presentation Post Lead" API consists of the following URL:

https://<environment-base-url>/PricePresentationPostLead

For example, in the AWL staging environment:

https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPostLead

A single post parameter is supported, which allows the passing of lead data in the AWL lead XML format:

  • LeadID (String)
    • A string containing the "LeadID" value returned by a previous successful call to the "Price Presentation Ping Lead" API that uniquely identifies the ping session and is used to associate this API call with the price bid returned by the ping
  • XmlString (String)
    • An XML string containing the lead object. The XML string must conform to the AWL Lead XML V1.5 Schema (included with this documentation)
    • XML string must be in UTF-8 format and must NOT include a Unicode byte order mark (BOM)
    • XML string must be equivalent to XML provided in previous successful call to the "Price Presentation Ping Lead" API

Example HTTP POST Data Payload

Back To Contents

The following represents an example post data payload for this API:

LeadID=<ping session identifier>&XmlString=<raw lead xml>

API Response

Back To Contents

The Price Presentation Post Lead API generally will return a standard HTTP 200 response code to indicate a successful operation. Note, however, that a 200 response does not indicate that AWL has successfully purchased the lead. The Data Affiliate partner must inspect the return value of the API to determine if AWL has accepted/purchased the posted lead.

When an HTTP 200 response is returned, the return result consists of a UTF-8 encoded XML string. The XML returned conforms to the "PricePresentationResult.xsd" XML schema document included along with this specification.

This schema contains a single XML type called "PricePresentationResultType".

  • Result
    • Values:
      • "OK"
        • Indicates that the request was successfully processed
        • Only indicates that the lead was successfully accepted/purchased in the event that the "Payout" value is non-zero
      • "ERROR"
        • Indicates that an error occurred during processing
  • ErrorType
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values:
      • "XML Validation"
      • "Data Validation"
      • "Login"
      • "Duplicate"
      • "Internal Server Error"
  • ErrorDescription
    • Provided when the "Result" is "ERROR" to provide additional information
    • Values consist of a descriptive human-readable string. A few examples:
      • "Invalid Username/Password"
      • "XML Parse/Validation Failure"
      • "Re-post of identical lead from same partner"
      • "Unknown error occurred processing lead"
      • Etc.
  • Payout
    • Provided when the "Result" is "OK", and the AWL system has successfully accepted/purchased incoming lead
    • Represents the expected/estimated payout, and will always match the bid price from the previous ping
  • LeadID
    • Provided when the "Result" is "OK", and the "Payout" is greater than $0.00
    • The Lead ID within the AWL system, useful for diagnostic and tracking purposes
    • This value should be logged/recorded in each partner's system
  • DataFieldValidation
    • Provided when the "Result" is "ERROR". Zero or more "DataFieldValidation" nodes may be included indicate which field or fields triggered an error response.
    • DataField
      • Identifies the data field (element) within the Lead XML that triggered a validation error
      • Values:
        • nameFirst
        • nameLast
        • nameMiddle
        • namePrefix
        • nameSuffix
        • addressStreet
        • addressStreet2
        • city
        • state
        • zipCode
        • phoneDay
        • phoneEvening
        • email
        • currentlyInsured
        • insuranceProvider
        • lengthOfCoverage
        • coverageExpiration
    • DataFieldErrorType
      • Identifies the type of validation error that occurred
      • Values:
        • Fail
        • Warning
    • DataFieldErrorMessage
      • Provides additional information related to the validation error that occurred
      • May be empty when no additional information is available

Staging Environment

Back To Contents

AWL provides a dedicated staging environment that partners may use to begin testing their integration with the Data Affiliate API.

The staging environment is completely isolated from our production environment, and therefore there are no restrictions on the lead data that can be posted into the system.

Note, however, that our duplicate detection rules (detailed earlier in the section "Duplicate Detection"), continue to apply within the staging environment. This means that each test lead that is successfully posted into the staging environment should have a unique email address, daytime phone number, and street address.

Note that the AWL staging environment currently resides on hardware infrastructure that is not as powerful as that used by the AWL production environment. Additionally, some tasks performed in the staging environment are "faked", and therefore will result in different latencies in staging versus production. Essentially, performance within the staging environment should not be considered indicative of the production environment.

If latencies are a concern, additional testing may be performed against the production environment using a restricted set of lead data to ensure that test leads are not inadvertently mixed with live production leads. Note that even when sending test leads into the production environment, certain internal operations can vary with respect to the operations performed on a real live lead. For more information on testing within the production environment, please refer to the "Production Environment" section later in this document.

Staging Environment Test Application

Back To Contents

A web-based test application is available for testing purposes. This simple web application allows partners to generate randomized test leads and post them through the V4.0 API. Alternatively, partners can copy-and-paste their own lead XML into the app for testing purposes as well.

https://dastaging-lm.dev.allwebleads.com/leads/DataAffiliateTestApp.aspx

Note: This testing web application doesn't currently default the "Lead Service URL" field, which is under the "Actions" header. For this test app to function appropriately, you must manually specify the base lead service URL prior to performing any actions.

The base lead service URL for the AWL staging environment is:

https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc

The following screenshot illustrates where this base lead service URL must be entered:

Image Modified

Staging Environment URLs

Back To Contents

The following URLs should be used for the HTTPS POST into the AWL system.

Note that these web service endpoints do not support HTTPS GET, and therefore will provide no useful output if entered into a web browser. Please use the staging environment test application mentioned earlier for attempting to experiment with the system ahead of your own development.

Send Lead Exclusive API:
https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/SendLeadExclusive

Price Presentation Ping API:
https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPing

Price Presentation Post API:
https://dastaging-lm.dev.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPost

Production Environment

Back To Contents

The AWL production environment is used to receive live leads from our Data Affiliate partners.

Production Environment URLs

Back To Contents

The following URLs should be used for the HTTPS POST into the AWL system.

Note that these web service endpoints do not support HTTPS GET, and therefore will provide no useful output if entered into a web browser. Please use the staging environment test application mentioned earlier for attempting to experiment with the system ahead of your own development.

Send Lead Exclusive API:
https://ws.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/SendLeadExclusive

Price Presentation Ping API:
https://ws.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPing

Price Presentation Post API:
https://ws.allwebleads.com/leads/4.0/LeadServiceHttpPost.svc/PricePresentationPost

Testing Within the Production Environment

Back To Contents

In general, all testing should be conducted within the AWL dedicated staging environment. On the other hand, certain classes or problems present themselves that require partners to send a very limited number of test leads into the AWL production system.

Unfortunately, it is not possible to send a test lead into the AWL production environment and receive a successful response.

It is possible to send a test lead into the production environment, which will result in a special error result that indicates that the operation would have had a high likelihood of succeeding.

To send a test lead into the AWL production environment, simply set the "ProductionEnvironment" flag in the lead XML to "true".

The ProductionEnvironment flag can be found within the XML here:

InsuranceRequest/AffliateInfo/ProductionEnvironment

If a test lead is not sent properly, it will be treated as a real lead. Please use extreme caution and care when submitting test leads into the AWL production environment.

Note, that duplicate detection rules continue to apply within the production environment even with regard to test leads. This means that each production-targeted test lead must have a unique email address, daytime phone number, and street address whenever contact information is provided.

Sample Client Code Snippets

Back To Contents

The following simplistic sample client code is provided for example purposes only. AWL does not make claims as to its quality of fitness for a specific purpose.

C# .NET Client Code Snippet

Back To Contents

Code Block

using System;
using System.IO;
using System.Net;
using System.Text;

public static String HttpPost()
{
    string url = "https://<server-name>/leads/4.0/LeadServiceHttpPost.svc/SendLeadExclusive";
    string xmlString = "<your-xml-here>";
    NetworkCredential credential = null
    int timeoutSeconds = 30;
    string contentType = "application/x-www-form-urlencoded";

    try
    {
        string postparams = String.Format("XmlString={0}", xmlString);

        HttpWebRequest myReq = (HttpWebRequest) WebRequest.Create(url);

        myReq.Method = "POST";
        myReq.Credentials = credential;
        myReq.ContentType = contentType;

        myReq.Timeout = timeoutSeconds * 1000; // convert to milliseconds
        StreamWriter writer = new StreamWriter(myReq.GetRequestStream());
        writer.Write(postparams);
        writer.Close();

        WebResponse webResponse = myReq.GetResponse();
        Stream receiveStream = webResponse.GetResponseStream();
        Encoding encode = System.Text.Encoding.GetEncoding("utf-8");

        // Pipe the stream to a higher level stream reader
        // with the required encoding format.
        StreamReader readStream = new StreamReader(receiveStream, encode);

        string responseInfo = readStream.ReadToEnd();
        readStream.Close();
        webResponse.Close();

        return responseInfo;
    }
    catch (WebException)
    {
        throw;
    }
}

PHP Client Code Snippet

Back To Contents

No Format

<?php
$endpoint = "https://<server-name>/leads/4.0/LeadServiceHttpPost.svc/SendLeadExclusive";
$content_type = "Content-Type: application/x-www-form-urlencoded";
$lead_xml = "<your-xml-string-here>";

if (!empty($lead_xml) && !empty($post_server))
{
    $postValue = urlencode($lead_xml);
    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_POST, "XmlString={$postValue}");
    curl_setopt($ch, CURLOPT_POSTFIELDS, "XmlString={$postValue}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array($content_type));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    try
    {
        $output = curl_exec($ch);
        $success = curl_errno($ch) == 0;
        curl_close($ch);
    }
    catch (Exception $e)
    {
    }
}
?>
Table of Content Zone