Follow

How to work with your leads via the API

This is part of the LeadConduit Classic API. Read an overview, or review common API parameters.

Use the Leads API to read lead data out of LeadConduit Classic based on campaign, date, and lead status. You can also reject, return, or mark leads as converted and delivered via this API. The "full access" API key is required for all lead API calls (see the overview for more about API keys).

An Important Note

This API is not designed to be polled frequently, so please exhibit responsible behavior when calling the API in a loop. A good rule of thumb: if you're polling for changes, limit your calls to once or twice per day. Evening and overnight hours are better than mid-day. If you make multiple simultaneous API requests (e.g., with multiple threads), the number of concurrent calls should not exceed three.

Lead Query Resources

GET https://api.leadconduit.com/leads

This resource lists leads. When making this call you must provide the campaign_id parameter. The response is automatically paged.

GET https://api.leadconduit.com/leads/#{lead_id}

This resource refers to a single lead. Replace #{lead_id} with the LeadConduit Classic ID of the lead you wish to retrieve.

GET https://api.leadconduit.com/leads/unsent

This resource lists all leads that have not yet been sent to the advertiser. These leads will always be "good." Leads that have been sent but could not be delivered do not show up in this list. This resource is automatically paged.

Lead Query Parameters

There are two ways to call the leads API. The first performs a query for leads based on certain criteria, and the second is specific to leads "routed" through multiple LeadConduit campaigns, using the source_lead_id parameter.

The first type of query is the most common.

  • campaign_id — required for all requests
  • source_id — optional, the ID of the account or site that sent the leads
  • recipient_id — optional, the ID of the account or recipient that received the leads
  • profile_id — optional, the ID of the lead profile to retrieve
  • start — optional, start date for query, YYYY-MM-DD format
  • end — optional, end date for query, YYYY-MM-DD format
  • status — optional, filter leads based on their current disposition. Possible values for status are:
    • good — include leads that have not yet been marked "bad"
    • invalid — include leads that were marked bad according to campaign constraints when they were posted into LeadConduit
    • rejected — include leads that were marked rejected during delivery to the advertiser's server
    • returned — include leads that were marked bad after delivery to the advertiser's server
    • converted — include leads that were marked converted after delivery to the advertiser's server

You may specify multiple status values in order to fetch various combinations of leads. For example, status=rejected&status=returned will fetch all leads that were either rejected when they were delivered to the advertiser, or after they were delivered to the advertiser. Leads that failed campaign validation will not be included.

The second way to query leads is by providing the source_lead_id parameter:

GET https://api.leadconduit.com/leads?source_lead_id=000000aef

This will return a list of leads that were created during a campaign-to-campaign lead delivery, based on the ID of the lead in the "source" campaign. This call is useful if you have a lead ID and want to find associated leads in "destination" campaigns.

The lead query parameters are not available when looking up leads by source_lead_id, so providing campaign_id, source_id, recipient_id, etc. will have no effect.

Lead Query Response

All calls to the lead query API return a JSON hash with five keys:

  1. count — the number of items being returned
  2. page_count — the number of pages (see paging)
  3. has_more — whether there are additional pages (see paging)
  4. campaign_id — the leads' campaign ID
  5. items — an array of lead records

An example response:

Lead Update Resources

In addition to querying leads, the API also allows you to delete leads as well as modify lead status and field values. See each resource for parameter and abbreviated response details. Calls act on leads synchronously (i.e., immediately) unless otherwise noted.

Deleting a lead

Use an HTTP post to the following URL to mark a lead for deletion.

DELETE https://api.leadconduit.com/leads/#{lead_id}

or
POST https://api.leadconduit.com/leads/#{lead_id}/delete

Deleting leads is an asynchronous operation, so the API returns HTTP 202 indicating that the lead will be deleted shortly (any other code indicates failure).

Once the lead is deleted, it will no longer be available to you or your lead sources. The statistics in the appropriate campaign will be adjusted in such a way that it will appear that the lead was never submitted. You may only delete leads in campaigns that you own.


###Rejecting a lead

Use an HTTP post to the following URL to mark a lead as rejected, with an optional reject reason.

PUT https://api.leadconduit.com/leads/#{lead_id}/reject

or
POST https://api.leadconduit.com/leads/#{lead_id}/reject

Rejecting a lead has no effect unless the lead is pending delivery. If the lead has already been delivered, use the lead return API call instead. The reason parameter specifies why the lead is being rejected. The reason parameter has a 75 character maximum length and will be truncated if it exceeds that length).

This is an asynchronous operation, so the API returns HTTP 202, indicating that the operation will be completed shortly (any other code indicates failure). Your lead sources, when logged into their LeadConduit accounts, will be able to see a summary of how many leads were rejected by reason.


###Rollback a Rejected Lead

Use an HTTP post to the following URL to undo a lead rejection.

PUT https://api.leadconduit.com/leads/#{lead_id}/rollback_rejection

or
POST https://api.leadconduit.com/leads/#{lead_id}/rollback_rejection

This is an asynchronous operation. If the lead rejection is successfully rolled back, the API returns HTTP 202. Any other code indicates that the lead rejection was not rolled back. Only the advertiser or owner of the lead's campaign may rollback a lead rejection. Calls to this resource by anyone else will generate an HTTP 401 Unauthorized.


###Returning a lead

Use an HTTP post to the following URL to return a lead to the lead source that provided it, with an optional return reason.

PUT https://api.leadconduit.com/leads/#{lead_id}/return

or
POST https://api.leadconduit.com/leads/#{lead_id}/return

Use the reason parameter to specify why the lead is being returned. (The reason parameter has a 75 character maximum length and will be truncated if it exceeds that length). If the lead is successfully returned, the API returns HTTP 200. Any other code indicates that the lead was not returned. Only the advertiser or owner of the lead's campaign may return the lead and calls to this resource by someone else will generate an HTTP 401 Unauthorized.

Your lead sources, when logged into their LeadConduit Classic accounts, will be able to see a summary of how many leads were returned by reason.


###Rolling back a Returned lead

Use an HTTP post to the following URL to undo a lead return.

PUT https://api.leadconduit.com/leads/#{lead_id}/rollback_return

or
POST https://api.leadconduit.com/leads/#{lead_id}/rollback_return

If the lead return is successfully rolled back, the API returns HTTP 200. Any other code indicates that the lead return was not rolled back. Only the advertiser or owner of the lead's campaign may rollback a lead return and calls to this resource by someone else will generate an HTTP 401 Unauthorized.


###Marking a lead delivered

Use an HTTP post to the following URL to mark a lead as delivered.

PUT https://api.leadconduit.com/leads/#{lead_id}/mark_delivered

or
POST https://api.leadconduit.com/leads/#{lead_id}/mark_delivered

If the lead status is successfully updated, the API returns HTTP 200. Any other code indicates that the lead was not updated. Only the advertiser or owner of the lead's campaign may mark a head as delivered and calls to this resource by someone else will generate an HTTP 401 Unauthorized.


###Converting a lead

Use an HTTP post to the following URL to mark a lead as converted on a specific date.

PUT https://api.leadconduit.com/leads/#{lead_id}/convert

or
POST https://api.leadconduit.com/leads/#{lead_id}/convert

The optional date parameter may be provided in order to specify the date the lead was converted. If no date parameter is provided, today's date will be used. Several date formats can be accepted (most callers use YYYY-MM-DD). Dates that cannot be parsed or dates that are in the future will result in an HTTP 400.

Marking the lead as converted will cause it to appear in the lead conversion report, available to the campaign owner and the campaign advertiser. If the API returns HTTP 200, then the lead has been successfully marked as converted. Any other code indicates the lead was not returned. Only the advertiser or owner of the lead's campaign may convert the lead. Calls to this resource by someone else will generate and HTTP 401 Unauthorized. A summary of how many leads were converted is only accessible by the campaign owner or advertiser.


###Rolling back a Converted lead

Use an HTTP post to the following URL to undo a lead conversion.

PUT https://api.leadconduit.com/leads/#{lead_id}/rollback_conversion

or
POST https://api.leadconduit.com/leads/#{lead_id}/rollback_conversion

If the lead conversion is successfully rolled back, the API returns HTTP 200. Any other code indicates that the lead conversion was not rolled back. Only the advertiser or owner of the lead's campaign may rollback a lead conversion and calls to this resource by someone else will generate an HTTP 401 Unauthorized.


###Updating a lead

Use an HTTP post to the following URL to update an existing value on the lead.

PUT https://api.leadconduit.com/leads/#{lead_id}

or
POST https://api.leadconduit.com/leads/#{lead_id}/update

If the lead is successfully updated, the API returns HTTP 200. Any other code indicates that the lead was not updated. If your call does not alter any of the lead values, you will receive an HTTP 400.

Any party that handled a lead may update a lead and calls to this resource by someone else will generate an HTTP 401 Unauthorized. The request body should contain the field names and values you wish to update. For example, to update lead data for the email field, the request body should contain email=john@doe.com. The update call will fail unless the lead already has a value in the email field.

A successful lead update response contains a list of the fields that were updated:

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

You must be logged in to comment.