LeadConduit by ActiveProspect

Integrating with External Services


LeadConduit allows you to send leads from your campaign to an external service via an HTTP GET or HTTP POST. The external service integration feature is a "hook" into the normal lead lifecycle; it occurs after the lead is submitted into LeadConduit, after LeadConduit has scrubbed the data against campaign requirements, but before the lead is delivered to its final destination. A lead which is currently being processed by an external service is shown in the PROCESSING status.

This feature is often used to send auto-responder messages using a third party Email Service Provider (ESP).

External service integrations are only available for the campaigns that you "own" or "manage."

What does the external service integration do for you?

It's a way to grab a copy of a lead before it is delivered. For example, if you want to send an email to the lead, you may choose to configure the "auto-responder integration" to post each lead to your email service provider, which will then send the lead an email on your behalf.  You may also use an integration to mark a lead INVALID (see the Response Parsing section below).

How do you set up an external service integration?

1. Getting Started

To configure an integration with an external service, click on the name of the campaign on the Campaigns tab; this shows the "Campaign View." Select one of the "external service integration" links.

External service integrations work over HTTP. You may choose to submit leads to any URL using this feature. Simply type in the URL and select the HTTP method. If you don't know which method to use, just use "POST".

2. Configure Parameters

Now you must configure which values you want to submit to the specified URL. The names of the parameters you specify depend on the names of the parameters that the external service expects to receive. By default, the external service integration will try to submit all fields in your campaign to the specified URL. You may add, remove, and rename fields to suit the requirements of the external service. You may also set a specific static value, if necessary. Typically this is used if you have a special code or identifier that you must submit with each HTTP request to the external service.

NOTE: if you add a new field to your campaign after setting up your parameters, you'll need to return the external service integration and add a new parameter there if you'd like to send the field value to the external service. LeadConduit will not automatically add new a campaign field as an external service parameter.

3. Try It!

After you've set up your parameters, click the "Try It!" button (disable your browser's pop-up blocker, if you're using one). If leads have already been submitted into your campaign, the specified parameters will be populated using one of your leads. You'll have an opportunity to change the lead data before you try out the integration. When you're ready to test the integration, click the "Send Request" button. This will make an HTTP request as you've specified and will display the result in your browser. The result includes a summary of the request that was sent and the response that was subsequently received. You can see the body of the HTTP response in the "Body" section.

4. Turn It On

If you get an error or something goes wrong, you can close the window and reconfigure the external service integration as necessary. After the integration is configured properly, click the "Turn On" button. This will cause leads to be processed by your new integration.

What happens behind the scenes when you set up an external service integration?

It's pretty simple, really. Just after a lead is posted into LeadConduit (and determined to be valid based on campaign settings) the system applies each external service that is turned on. For each service, the lead data is extracted from the lead and an HTTP request is sent to the URL specified in the external service configuration.  External services are not applied in any guaranteed order, nor can the result of one integration affect another integration. 

What if an error occurs while my lead is being sent to an external service?

If an error is encountered while the lead is being sent to the external service, LeadConduit will try to resend your lead every minute until it is successful. If you would like LeadConduit to stop retrying after a certain amount of time, this may also be configured for each external service integration. If you decide to use this setting, you must also tell LeadConduit what to do if the lead cannot be successfully sent: either mark it as INVALID or deliver the lead anyway.

Response Parsing

The external service can understand LeadConduit version 2 responses.  This feature must be enabled using the appropriate checkbox on the external service configuration page.  If the response indicates a failure, the lead will be marked INVALID.  If the response indicates an error, the external service will behave pursuant to the error handling description outlined above.  External services configured for a campaign will not be affected by the outcome of another in the same campaign.

In order to work correctly, the feature must be enabled, and every response given must start with this DOCTYPE declaration:

<!DOCTYPE response SYSTEM "https://production.leadconduit.com/ap/dtd/response-v2-basic.dtd">

Additionally, every response given must adhere to the document type definition given in the DOCTYPE declaration.  To see that document type definition, please refer to  https://production.leadconduit.com/ap/dtd/response-v2-basic.dtd.

If you require additional information on what a document type definition is used for or why we require it, please refer to the wikipedia page on the subject.


last updated 9/19/2008 4:02 PM