Lead Returns API V2.0

Skip to end of metadata
Go to start of metadata
Terms and Conditions
Please read our Terms and Conditions

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
Director, Business Development
jeremy.attick@allwebleads.com
Office: 888-522-7355 x115
Mobile: 720-371-9540
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

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.

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.

Realistically, some level of downtime will be required to allow for routine maintenance. Any necessary downtime 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

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

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.

The AWL system supports receiving lead return requests in a manner that is independent and isolated for each individual transaction.

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.

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

Sample Response

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.

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

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 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

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.