Child pages
  • Data Affiliates V4.0 API Partner Specification

Versions Compared

Key

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

...

Date

Rev.

Comments

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="84ab3dd6d06bd2da-5b1b6a98-4e1a42b1-b6f08617-658a4a1aff9466dd75f699c6"><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="7bd06054911c1903-84c3231a-4940461b-a334ba08-58f3a419206ce5d0dedc4c3c"><ac:plain-text-body><![CDATA[

4/07/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="1e4a3dba53b93796-23980a54-4fea4ea1-9adda0d2-1a560522bf27e3d034584b5b"><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="822a31e687ab657d-035b92f9-440441b3-99fc8467-f9bcc5a920ec3efef3059c03"><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>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b6b4ed6a98e6633b-a351da14-40014263-81a7809c-01439a77c2201e9e610730d2"><ac:plain-text-body><![CDATA[

5/02/2011

4.4

Fixed incorrect documentation for Price Presentation staging and production URLs [JDR]

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

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="9ca3c685fec5ad3f-084c5afd-4feb4c1a-a5d688bb-16cc9ebf31dfb2e99b6a2fe2"><ac:plain-text-body><![CDATA[

5/12/2011

4.5

Updated "Staging Environment Test Application" section to remove note about lead service URL not being defaulted, as it now is. [JDR]

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

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="13c93ea896c4c15e-775f7131-4acc4df4-b4f5b7c4-985a6f164699b713e4fd0b0b"><ac:plain-text-body><![CDATA[

5/17/2011

4.6

Updated spec with latest insurance provider carriers, split list between Undersold supported and current insurance supported carriers. [JDR]

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

7/26/2011

4.7

Updated spec and schemas to include new Leg Ping and Post Lead APIs.

10/6/2011

4.8

Updated features section to include information about the Lead Source Id parameter.

3/5/2012

4.9

Updated spec/schema to add support for LeadIdToken parameter.

4/23/2012

4.10

Updated schema and added description for "NotSoldExclude" distribution directives.

8/2/2012

4.11

Added AWL/LeadiD Getting Started Guide information to enhance LeadIdToken parameter information.

7/15/2013

4.12

Added LeadMetaData node to the schema which has the following elements in it: IpAddress, LeadBornOnDateTimeUtc, and UserAgent.

8/1/2013

4.13

Updated the Insurance Carrier lists.

8/5/2013

4.14

Schema was updated to add new optional parameters. Parameters include: marital status for health, home, renters, and life lead types, gender for home and renters lead types, first name and last name for health lead dependents, and "is military" indicator for health lead type.

3/13/2014

4.15

Lead samples were added under the Lead Types section.

5/27/2014

4.16

Added full list of possible API ping/post responses.

8/26/2014

4.17

Added optional "Motorcycle" element to Vehicle node in AutoInsuranceRequest.

11/12/2014

4.18

Added sample raw ping/post request/responses for Auto and Health leads.

1/22/2015

4.19

Updated lead schema. Removed duplicate Marital element in Health, LTC, and Disability types. Added QualifyingLifeEvent element in Health type.

11/24/2015

4.20

Updated the Current Provider Carrier List in order to remove carrier strings containing ampersands. The ampersands have been changed to "and" instead.

4/25/2016

4.21

Updated the Undersold Carrier List and added several new carriers

5/11/2017

4.22

Added support for Inbound Warm Transfer Call Affiliates. Updated LeadXMLSchema.xsd and PricePresentationResult.xsd.

...

  • 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

Price Presentation Ping Inbound Warm Transfer API

Back To Contents

The "Price Presentation Ping Inbound Warm Transfer" API is used to send the data associated with warm transfer to the AWL system to receive a bid on the warm transfer (this is often referred to as "price presentation ping-post" in the industry).

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

The warm transfer data must be provided in its entirety, although all personally identifiable information for the primary applicant is considered optional. The AWL system evaluates the provided warm transfer 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 warm transfer.

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 Inbound Warm Transfer" API call to offer the warm transfer for sale at the previously bid price point. Note that a warm transfer bid price and its ping session identifier is valid only for up to five minutes.

The "Price Presentation Ping Inbound Warm Transfer" 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 warm transfer 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

List of possible responses

The Price Presentation Ping Inbound Warm Transfer 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 warm transfer. The Data Affiliate partner must inspect the return value of the API to determine if AWL has indeed placed a bid on the warm transfer.

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 warm transfer
    • Represents the expected/estimated payout associated with a potential subsequent post of the same warm transfer
  • LeadID
    • Provided when the "Result" is "OK", and the "Payout" is greater than $0.00
    • The Lead ID value is not a "real" warm transfer identifier within the AWL system, but instead is actually a ping session identifier that must be used in a subsequent "Price Presentation Post Inbound Warm Transfer" API call if the partner chooses to offer the full warm transfer data 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
  • AllowTransfer
    • Boolean field that indicates whether or not the warm transfer has been accepted.

Price Presentation Post Inbound Warm Transfer API

Back To Contents

The "Price Presentation Post Inbound Warm Transfer" API is used to offer warm transfers to sell after those warm transfers have successfully been bid upon by the AWL system via a previous call to the "Price Presentation Ping Inbound Warm Transfer" API.

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

The warm transfer 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 Inbound Warm Transfer" API. This "LeadID" value represents a session identifier that associates the post with the ping. Note that a warm transfer 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 warm transfer data via this API, the personal identifying information will be validated. If the identifying information cannot be validated, the warm transfer will rejected. Additionally, the personal identifying information will be used to determine if the warm transfer data is considered a duplicate within the AWL system. If the warm transfer data 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 Inbound Warm Transfer" 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 warm transfer 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 Inbound Warm Transfer" 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 Inbound Warm Transfer" 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

List of possible responses

The Price Presentation Post Inbound Warm Transfer 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 warm transfer. The Data Affiliate partner must inspect the return value of the API to determine if AWL has accepted/purchased the posted warm transfer.

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 warm transfer 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 warm transfer
    • 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

...

Sample payload data and responses

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

List of possible responses

...

Sample payload data and responses

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

List of possible responses

...