about configuring lead delivery
Leads can be delivered via HTTP using GET or POST. If you have the option to use POST then you should, for the reasons explained here. Regardless of whether you are using GET or POST, you are required to enter a URL, the parameters, and some information to help determine whether the delivery was a success, failure, or error.
Originating IP
Lead delivery traffic can originate from the following IPs:
- 174.143.120.208
- 174.143.120.209
- 174.143.120.210
- 174.143.120.211
- 174.143.120.212
- 174.143.120.213
- 174.143.120.214
- 174.143.120.215
- 174.143.120.242
- 174.143.120.243
- 208.43.31.178
- 208.43.39.228
- 208.43.39.229
- 208.43.39.230
- 208.43.39.231
- 74.86.109.58
- 75.126.200.56
- 75.126.200.57
- 75.126.200.58
- 75.126.200.59
- 74.86.109.59
- 75.126.200.60
- 75.126.200.61
- 75.126.200.62
- 75.126.200.63
- 74.86.109.60
- 75.126.200.88
- 75.126.200.89
- 75.126.200.90
- 75.126.200.91
- 173.192.20.34
Posting URL
The posting URL is required. This is the HTTP address where the leads should be sent. We recommend that you use SSL (https://...) if it is provided by the receiving server. If you do not use SSL, lead data will be sent without encryption, thus exposing your lead information as it is sent across the Internet to the receiving server. You may use variable placeholders in the posting URL.
Parameters
Parameters are configured using a special format. If you've worked with HTTP before, then you probably recognize that the default parameters look a lot like the query string format (i.e. firstname=Joe&lastname=Blow&email=joeblow@yahoo.com). There's a small but important twist to this familiar format: the parameter values can be special variable placeholders. A placeholder is identified by the #{variable_name} format. That is, each variable placeholder begins with the pound sign and a left bracket, and ends with a right bracket. The pound sign, brackets, and text between them will be replaced with lead data just before the lead is delivered. Notice that when you set up a new delivery, the parameters contain variable placeholders for each field that's defined in your campaign.
If you want to deliver a value that doesn't change from lead to lead, you can do it by omitting the variable placeholder around the parameter value (i.e. affiliate_id=abc123).
Normally, parameters that come in to LeadConduit with no value (i.e., blank form fields) are not sent in the HTTP delivery. Check the "send all parameters" checkbox to change that, and have all parameters sent, even if they're empty.
For advanced value handling, there are a number of additional variable placeholders available for your use. Click the "variable placeholders" link next to the parameters input field to see a list of all the available variable placeholders.
Response Handling
When leads are delivered via HTTP, the recipient server will give a response. LeadConduit parses this response using regular expressions to determine the outcome of the delivery.
Pattern for valid response
The first check for every response is whether or not it is valid. If the response matches the pattern for valid response, LeadConduit will continue evaluating it (see below). Otherwise, the delivery is treated as an error and LeadConduit will continue trying to deliver the lead, until a valid response is received. During this time, the lead will be in PENDING state.
This pattern must include exactly one regular expression "match group". This is a sub-part of the regular expression, denoted by a pair of parentheses, which will be used in the later phases of response handling.
Examples
| (.*) | Makes the entire response a match group. Can be used if the response is a single word or value, such as "SUCCESS", "FAILURE", "TRUE", "FALSE", etc. With this pattern, any response at all, even an empty one, will be valid. |
| .*<status>(.*)</status>.* | Sets the match group to the contents of an XML-style "status" tag. Using this pattern, any response that contains the text "<status>" and "</status>" will be valid. |
| .*result=(pass|fail).* | This pattern will match responses if they contain either "result=pass" or "result=fail" within them. The value of the match group will be either "pass" or "fail". Note that with this pattern, a response such as "result=unknown" would be invalid, and treated as an error. |
Pattern for ACCEPT response
Once a response is known to be valid, it can be further evaluated to see if the delivered lead was accepted or rejected. The pattern for ACCEPT response is used to see if the lead was accepted by the recipient. Any response that doesn't match this pattern will be interpreted as a REJECT. It is unnecessary to define the pattern for a REJECT response; it is simply any valid response that is not an ACCEPT.
The ACCEPT response is compared to the contents of the "match group" from the pattern for valid response (see above).
For example, suppose you set the pattern for valid response to: ".*<status>(.*)</status>.*". In this case, the pattern for ACCEPT response should be whatever comes in the "<status>" tag, that means the lead was accepted, such as "success" or "accepted". In this example, a response that contains "<status>rejected</status>" would be treated as a reject.
Pattern for reject reasons
When a reject response is received, the pattern for reject reasons can be used to capture the reason(s) why the lead was rejected. This setting is not required, but your bad lead report will include these reasons, if they're available. Of course, this does not apply to ACCEPT responses.
The text available to search for reject reasons is the contents of the match group defined above in the valid response pattern. Within that match group, this reject reason pattern defines which part contains the reason why the lead was rejected (e.g., "duplicate", "Zip code not serviced" or "unable to reach by phone").
This pattern must include at least one match group, itself. Each group matched in a reject response is saved as a a reason why the lead was rejected. Multiple reason-matching groups are permitted.
Response Handling Example
For example, assume the following configuration;
| Pattern for valid response: | <response>(.*)</response> |
| Pattern for ACCEPT response: | <status>accepted</status> |
| Pattern for reject reasons: | .*<reason>(.*)</reason>. |
The valid response pattern ensures that the response begins and ends with the XML tags "<response>" and "</response>". If the response doesn't match this pattern, the response is considered an error, and LeadConduit will continue to try re-delivering the lead, as configured. If the response does match, then the "(.*)" match group makes everything in between the tags available for later evaluation.
If the text between the "<response>" tags is exactly equal to "<staus>accepted</status>", then the lead will be marked ACCEPTED, and processing stops. If that text is anything else, then the lead will be marked as REJECTED, and the 3rd pattern will be applied.
The "(.*)" in the reject reason pattern defines a new match group which is applied to the same text that comes out of the valid response evaluation from before, If that text has the tags "<reason>" and "</reason>" anywhere within it, then everything between them is saved as the reject reason for this lead. Note that including ".*" before and after the reject reason pattern allows it to match even if there is other text before or after the tag. That is, there may be other text inside the "<response>" tag besides the "<reason>" tag, but it will be ignored.
Given this configuration, here is how various responses would be evaluated:
| EXAMPLE RESPONSE | RESULT GIVEN THE EXAMPLE CONFIGURATION |
|---|---|
| <response> <status>accepted</status> </response> | lead marked ACCEPTED |
| <response> <status>rejected</status> </response> | lead marked REJECTED, but no reason recorded (leads like this will show up as "unknown reason" on the Bad Lead Summary report) |
| <response> <status>rejected</status> <reason>duplicate address</reason> </response> | lead marked REJECTED with reject reason of "duplicate address" |
| <response> <status>rejected</status> <date-time>11/04/2008<date> <reason>duplicate address</reason> <server-rev>V8.9.1</server-rev> </response> | lead marked REJECTED with reject reason of "duplicate address" This is the same as the previous example, but with additional tags in the response. Due to the leading and trailing ".*" in the reject reason pattern, however, the extra information is ignored. |
| <response> <date-time>11/04/2008<date> <status>accepted</status> <server-rev>V8.9.1</server-rev> </response> | lead marked REJECTED. The extra data before and after the <status> tag (<date-time> and <server-rev>) are not allowed with the given accept response pattern. If that pattern were changed to ".*<status>accepted</status>.*", then this lead would be marked accepted. |
| <error>Database unavailable</error> | delivery error; LeadConduit will continue trying to deliver |
Recommended server response format
If you have control over the format used in the recipient server responses, then we recommend that you adopt the same format we use to respond to leads posted into LeadConduit. This uniformity insures maximum ease of use and information sharing between the recipient server and LeadConduit.
For more information, see Understanding the LeadConduit Server Response.
Setting up response parsing for LeadConduit compatible delivery responses
If your server responds with the standard LeadConduit response, then you should use the following response parsing patterns:
- Pattern for valid response: (.*<result>(?:success|failure|queued)</result>.*)
- Pattern for ACCEPT response: .*<result>(?:success|queued)</result>.*
- Pattern for reject reasons: .*<reason>(.*)</reason>.*