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="bcc76363afe53797-87ea8fa2-40f74468-ae919bee-caf861c671c605a1e71f403d"><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="491fca1a0c5a66b5-c5c28953-429b411c-8f5987b3-93b610ba07b56be727ca84b7"><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="7d1aa292735377e9-0df3e0fb-4148423d-993297aa-67634d5627422ee9df08805b"><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="c3a686531c77b5e7-1a823986-47fb4335-be1e9cba-8f77f3519462afe070ecf8b6"><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="39794af188b8a432-8192f553-47ed4b08-b522a7b3-0564cfa5db3ba512494f2f90"><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="de29ff9616efc81b-7ce80f80-43c247fa-917c85a3-f858e16a41eb2054663d327d"><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="63d337e61e35d7e6-9e9ed1d0-46c948e0-916e834f-43237039d00c1c8afce73a9a"><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/25/2011

4.7

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

...

<?xml version="1.0" encoding="utf-8"?>
<PricePresentationResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="https://www.insuranceleads.com/partner/PricePresentationResult.xsd">
<Result>OK</Result>
<LeadID>31</LeadID>
<Payout>25.36</Payout>
<Legs>
    <Leg><LegID>9</LegID><LegGUID>1ec301b331474c55bbb7517ee7055d5d</LegGUID><Payout>6.96</Payout><CarrierName>Independent</CarrierName><LicenseNumber>173007</LicenseNumber></Leg>
    <Leg><LegID>10</LegID><LegGUID>a216dd235c274b56a50c573028ace3d7</LegGUID><Payout>5.2</Payout><CarrierName>Health Choice One</CarrierName></Leg>
    <Leg><LegID>11</LegID><LegGUID>744587c381f247a4b6151cffd627d96c</LegGUID><Payout>4.8</Payout><CarrierName>American Insurance</CarrierName></Leg>
    <Leg><LegID>12</LegID><LegGUID>389f84c26ee44183a1b4edfd4eb3adb2</LegGUID><Payout>4.8</Payout><CarrierName>US Health Group</CarrierName></Leg>
    <Leg><LegID>13</LegID><LegGUID>34880766679b4a6d8deddee9c51b3110</LegGUID><Payout>3.6</Payout><CarrierName>Independent</CarrierName><LicenseNumber>162232</LicenseNumber></Leg>
</Legs>
</PricePresentationResult>

Legs Post Lead API

Back To Contents

The "Legs Post Lead" API is used to offer legs for a given lead to sale after those legs have successfully been bid upon by the AWL system via a previous call to the "Legs Ping Lead" API.

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 "Legs Ping Lead" API. This "LeadID" value represents a session identifier that associates the post with the ping. Note that a lead and its associated leg prices and its ping session identifier are valid only for up to two minutes. If a call to this API uses a ping session identifier that is more than two (2) minutes old, that call will be rejected.

The post Lead Xml will also need to indicate leg offers that have been accepted. This is done by including in the lead Post Xml the LegID and LegGUIDs of the accepted leg offers that were returned in the previous call to the "Legs Ping Lead" API.

With the exception of the ping-time optional personally identifying information and accepted leg offers indicated in the Lead post Xml, 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 "Legs Post Lead" API consists of the following URL:

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

For example, in the AWL staging environment:

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

Two post parameters are supported, which allow the passing of lead data in the AWL lead XML format and indicating what the corresponding lead is:

  • LeadID (String)
    • A string containing the "LeadID" value returned by a previous successful call to the "Legs Ping Lead" API that uniquely identifies the ping session and is used to associate this API call with the leg price bids 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 "Legs 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 Legs 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 and its associated legs. The Data Affiliate partner must inspect the return value of the API to determine if AWL has accepted/purchased the posted lead and its associated legs.

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 and the offered legs
    • Represents the expected/estimated payout of all the legs that have been sold to AWL
  • 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

...