Versions Compared

Key

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

...

Info
titleTerms and Conditions

Please read our Terms and Conditions

Anchor
_tocTop
_tocTop

Table of Contents
maxLevel3
outlinetrue
locationtop
stylenone
typelist

Document Info

Back To Contents

Contact Information

Back To Contents

Company Address

Business Contacts

Technical Contacts

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

J.R. Attick

Andi Whittaker
Director,

Business Development

Customer Success  

jeremy

andrea.

attick@allwebleads

whittaker@allwebleads.com 
Office:

888

512-

522-7355 x115
Mobile: 720-371-9540

942-6197  

AWL Operations Team Alias
operations@allwebleads.com

Ken Armond
Software Engineer
kenneth.armond@allwebleads.com
Direct: 512-222-4472 
Jeremy Remington
Director of Platform Software
jeremy.remington@allwebleads.com
Direct: 512-279-3111

AWL Partner Integrations Team
PartnerIntegrations@allwebleads.com

Revision History

Back To Contents

Date

Rev.

Comments

6/18/2014

2.0

Initial draft [KCA]

10/29/2014

2.1

KCA

Introduction

Back To Contents

This document details the information necessary for partners to begin returning purchased leads from All Web Lead, Inc. (referred to hereafter as AWL) via the AWL Version 2.0 Lead Return Service web service API. 

The Lead Return Service is only made available to select partners, based on contractual details.

Technical Overview

Back To Contents

Protocol

Back To Contents

AWL requires partners to access the AWL Lead Return Service API using a client that supports HTTP POST web services.

Transport Security

Back To Contents

AWL requires that all partners 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 consumers of the Lead Return Service will be assigned a unique customer identifier in addition to a password. Both the identifier and the password must be provided in each API call in order to allow AWL to identify the partner requesting a lead return.

Content-Type
ReturnLead requests are required to be of content-type application/x-www-form-urlencoded. All requests to this endpoint must contain the following header:
Content-Type: application/x-www-form-urlencoded

Content-Type

Back To Contents

ReturnLead requests are required to be of content-type application/x-www-form-urlencoded. All requests to this endpoint must contain the following header:

Content-Type: application/x-www-form-urlencoded

Firewall Restriction

Back To Contents

Access to the AWL Lead Return Service API is firewall-restricted. 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 partners to AWL may be transmitted successfully and accurately.

...

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

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.

...

This means that if a duplicate lead is submitted for return, the response will be the same as the original response. For example, if a lead was returned and the response was "Return queued for asynchronous processing," subsequently calling this method to submit the same lead will give the same response, even if the return has since been processed, and the true status of the lead is now "Return completed".

Timeout and Retries

Back To Contents

AWL expects Lead Return Service 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 potentially 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.

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 a result in the shortest amount of time possible.

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.

Simultaneous Requests

Back To Contents

To ensure the most expedient acceptance our lead return requests, the AWL systems may accept lead return requests in a multi-threaded (simultaneous) fashion, either from multiple partners or from one partner.

...

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.

Web Service API Details

Back To Contents

As indicated earlier, the Version 2.0 Lead Return Service API consists of a HTTP POST web service made available over HTTPS.

API Documentation

Back To Contents

ReturnLead Operation

Back To Contents

This method submits a lead return request. The return may be immediately accepted, immediately rejected, or queued for asynchronous processing internally within AWL.

This method is idempotent. This means that if a duplicate lead is submitted for return, the response will be the same as the original response. For example, if a lead was returned and the response was "Return queued for asynchronous processing," subsequently calling this method to submit the same lead will give the same response, even if the return has since been processed, and the true status of the lead is now return "Return completed".

Parameters

Back To Contents

Name

Required?

Data Type

Max Size

Description

customerId

Yes

Integer

32 bit

Customer ID assigned by All Web Leads.

password

Yes

String

255 chars

Password assigned by All Web Leads.

vendor_lead_id

Yes

Integer

32 bit

Lead ID assigned by All Web Leads when the lead was originally submitted.

return_reason_code

Yes

Integer

32 bit

Reason for returning the lead (see Appendix for allowed values).

return_comments

No

String

255 chars

A memo field for any comments about the return. This field can be retrieved via the CheckLeadReturnStatus method.

request_id

No

String

255 chars

A unique ID from the client associated with the lead return request.

postback_url

No

String

255 chars

Custom field. Do not use unless instructed otherwise.

recipient

No

String

255 chars

Custom field. Do not use unless instructed otherwise.

Response

Back To Contents

Name

Data Type

Max Size

Description

ResponseCode

Integer

32 bit

Response Code indicating status of request.

ResponseSummary

String

16 chars

Category of the Response Code: Success, Pending, Fail, or Error.

ResponseMessage

String

255 chars

Human-friendly description corresponding to Response Code.

CheckLeadReturnStatus Operation

Back To Contents

This method is used to check the status of a previously submitted lead return. 

Parameters

Back To Contents

Name

Required?

Data Type

Max Size

Description

customerId

Yes

Integer

32 bit

Customer ID assigned by All Web Leads.

password

Yes

String

16 chars

Password assigned by All Web Leads.

vendor_lead_id

Yes

Integer

32 bit

Lead ID assigned by All Web Leads when the lead was originally submitted.

Response

Back To Contents

Name

Data Type

Max Size

Description

ResponseCode

Integer

32 bit

Response Code indicating status of request.

ResponseSummary

String

16 chars

Category of the Response Code: Success, Pending, Fail, or Error.

ResponseMessage

String

255 chars

Human-friendly description corresponding to Response Code.

DeclineCode

Integer

32 bit

Decline Code, or 0 (pending).

DeclineMessage

String

255 chars

Human-friendly description corresponding to Decline Code.

Valid Response Codes

Back To Contents

(see Appendix for full list)

Response Code

Summary

Description

2

Success

Return completed

4

Pending

Return queued for asynchronous processing

5

Fail

Return declined

7

Error

Internal error

8

Error

Invalid Customer ID or password

9

Error

Invalid reason code

10

Error

Lead not found, or was not sold to this customer

11

Error

Lead is too old to be returned

13

Error

Lead has already been returned

Sample Raw Request

Code Block
POST https://dastaging-lm.dev.allwebleads.com/leads/1.0/ReturnServiceHttpPost.svc/ReturnLead HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: dastaging-lm.dev.allwebleads.com
Content-Length: 148
Expect: 100-continue
Connection: Keep-Alive

vendor_lead_id=47387862&customerId=94314&password=MyPassword&return_reason_code=11&return_comments=Didn't request a quote

...

Code Block
<LeadReturnResponse>
	<ResponseCode>4</ResponseCode>
	<ReturnStatus>Pending</ReturnStatus>
	<Description>Return queued for asynchronous processing</Description>
</LeadReturnResponse>

Staging Environment

Back To Contents

AWL provides a dedicated staging environment that partners may use to begin testing their integration with the Lead Return Service API.

...

If latencies are a concern, additional testing may be performed against the production environment using a restricted set of data to ensure that test lead returnss are not inadvertently mixed with live production lead returns. Note that even when sending test lead returns into the production environment, certain internal operations will vary with respect to the operations performed on a real live lead.

Staging Environment URL

Back To Contents

https://dastaging-lm.dev.allwebleads.com/leads/1.0/ReturnServiceHttpPost.svc/ReturnLead

Production Environment

Back To Contents

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

Production Environment URL

Back To Contents

https://ws.allwebleads.com/leads/1.0/ReturnServiceHttpPost.svc/ReturnLead

Appendix: Response Codes

Back To Contents

Response Code

Summary

Description

1

Success

Request was successful

2

Success

Return completed

4

Pending

Return queued for asynchronous processing

5

Fail

Return declined

6

Fail

Return declined - This return reason is available only for subscription members.

7

Error

Internal error

8

Error

Invalid Customer ID or password

9

Error

Invalid reason code

10

Error

Lead not found, or was not sold to this customer

11

Error

Lead is too old to be returned

12

Error

Lead has not been returned

13

Error

Lead has already been returned

14

Error

Return declined - Call transfer customer accounts cannot return leads

Appendix: Reason Codes

Back To Contents

Reason Code

Description

Product Type

Notes

1

All numbers provided are disconnected or fax

Leads

 


2

Lead is a duplicate already received from All Web Leads

Leads

 


3

Contact is another agent testing the system

Leads

 


4

Contact is a student researching a school project

Leads

 


6

A language barrier exists with the contact

Leads

 


11

Prospect did not request quote

Leads

 


20

All numbers provided are wrong numbers

Leads

 


22

Prospect's name is obviously incorrect e.g. Mickey Mouse

Leads

 


23

Prospect's phone number is obviously incorrect e.g. 555.555.5555

Leads

 


26

Consumer Insured By My Primary Carrier

Leads

Only available to Premium subscribers

27

Caller Disconnected

Calls

 


28

Verification/Knock Out Question Review

Calls

 


29

Call Not Answered Review

Calls

 


30

Call Received While Paused

Calls

 


33

Home lead is actually a renters lead.

Leads

 


Appendix: Decline Codes

Back To Contents

Decline Code

Description

1

Spoke to contact, information on form verified

2

Is available with optional filter

4

Unable to verify information

6

Return declined - This return reason is available only for subscription members

Appendix: Sample C# client code

...