Leads

Free accounts do not have access to Leads (https://app.leadconduit.com/leads) and will receive a 401 (Unauthorized) error when trying to access it

Event

An event tracks what happened with a lead at a particular step in a flow. An event is a self-contained snapshot of the state of the lead at the time the lead visited the step. It contains a full copy of all lead data, along with all data that was appended before that step. Every event contains the below properties.

id
required
string (ID) ^[0-9a-fA-F]{24}$

24 character alpha-numeric BSON identifier

outcome
required
string

The outcome of the event

Enum: Description
success

The source was notified in the response that the lead was accepted

failure

The source was notified in the response that the lead was rejected

error

The source was notified in the response that an error occurred while processing the lead

reason
required
string

The reason for a failure or error outcome

object (Source Variables)

All data available at the time LeadConduit started processing this event

host
string
start_timestamp
integer

The number of milliseconds elapsed since epoch at the start of the step processing

end_timestamp
integer

The number of milliseconds elapsed since epoch at the end of the step processing

object (Firehose)
ms
integer

The number of milliseconds that elapsed while processing the lead

wait_ms
integer

The number of milliseconds that LeadConduit spent waiting for all recipients to respond

overhead_ms
integer

The number of milliseconds of overhead that LeadConduit added while processing the step

lag_ms
integer
total_ms
integer

The number of milliseconds that elapsed since the lead was submitted

handler_version
string (SemanticVersion)

The version of the lead handler

version
string (SemanticVersion)

The schema version of the event

cap_reached
boolean
object (PingLimit)

The ping limit configuration is defined in a flow on a source, or directly on the flow itself. The configuration controls the behavior of the ping limit by setting the maximum and the duration. The counter for a ping limit is kept as a standalone record which shares ping limit's ID.

object (PingLimit)

The ping limit configuration is defined in a flow on a source, or directly on the flow itself. The configuration controls the behavior of the ping limit by setting the maximum and the duration. The counter for a ping limit is kept as a standalone record which shares ping limit's ID.

ping_limit_reached
boolean
expires_at
string <date-time> (Timestamp)

The time this event will be automatically deleted from LeadConduit (events are retained for 90 days)

type
required
string

Recorded after a source submits a lead to a flow

module_id
string (ModuleID)

The integration module ID configured for the source

package_version
string (SemanticVersion)

The semantic version of the integration package

object or null (acceptance-criteria)

The acceptance criteria configured on the source when the lead was processed

step_count
integer

The number of steps processed for this lead (>= 0 and <= total number of steps)

appended
object

All data appended while handing the lead

object (HttpRequest)

The inbound HTTP request

object (HttpResponse)

The inbound HTTP response

{
  • "id": "5fd4371e940df5a34a3888b2",
  • "outcome": "success",
  • "reason": "string",
  • "vars": { },
  • "host": "string",
  • "start_timestamp": 0,
  • "end_timestamp": 0,
  • "firehose": {
    • "credential_id": "5fd4371e940df5a34a3888b2",
    • "enabled": true,
    • "bucket": "string",
    • "prefix": "string"
    },
  • "ms": 0,
  • "wait_ms": 0,
  • "overhead_ms": 0,
  • "lag_ms": 0,
  • "total_ms": 0,
  • "handler_version": "string",
  • "version": "string",
  • "cap_reached": true,
  • "flow_ping_limits": {
    • "id": "5fd4371e940df5a34a3888b2",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "2019-08-24T14:15:22Z"
    },
  • "source_ping_limits": {
    • "id": "5fd4371e940df5a34a3888b2",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "2019-08-24T14:15:22Z"
    },
  • "ping_limit_reached": true,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "type": "source",
  • "module_id": "string",
  • "package_version": "string",
  • "acceptance_criteria": {
    • "rule_set": {
      • "id": "1aacd0",
      • "op": "and",
      • "rules": [
        • {
          • "id": "1aacd0",
          • "lhv": "lead.state",
          • "op": "is equal to",
          • "rhv": "TX",
          • "rule_set": { }
          }
        ]
      },
    • "outcome": "failure",
    • "reason": "string"
    },
  • "step_count": 4,
  • "appended": { },
  • "request": {},
  • "response": {
    • "status": 201,
    • "status_text": "Created",
    • "version": "1.1",
    • "headers": { },
    • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
    • "timestamp": 0
    }
}

List all events

The /events resource is used to query events generated while handling leads. For each lead, one event is generated for each configured flow step that handles the lead. After lead processing completes, a source event is also recorded.

SecurityAPIKey
Request
query Parameters
after_id
string (ID) ^[0-9a-fA-F]{24}$

Return only events that were created after the one with this ID (exclusive)

Example: after_id=5fd4371e940df5a34a3888b2
before_id
string (ID) ^[0-9a-fA-F]{24}$

Return only events that were created before the one with this ID (exclusive)

Example: before_id=5fd4371e940df5a34a3888b2
start
string <date-time> (Timestamp)

Return only events that were created at or after this time

end
string <date-time> (Timestamp)

Return only events that were created at or before this time

Array of Binary Rule (object) or Unary Rule (object) (Rule)

Rules to select matching events

include
string

A field to include. Can be used multiple times to include multiple fields. Cannot be used with exclude.

exclude
string

A field to exclude. Can be used multiple times to exclude multiple fields. Cannot be used with include.

limit
integer [ 1 .. 1000 ]

The maximum number of events to return (maximum limit is 1000, default 100)

sort
string

The results are sorted by date. Use asc to sort by oldest first or desc to sort by newest first. Defaults to desc.

Responses
200

OK

401

Authorization information is missing or invalid.

get/events
Request samples
Response samples
application/json
[
  • {
    • "type": "source",
    • "id": "5fd4371e940df5a34a3888b2",
    • "outcome": "success",
    • "reason": "string",
    • "vars": { },
    • "host": "string",
    • "start_timestamp": 0,
    • "end_timestamp": 0,
    • "firehose": {
      • "credential_id": "5fd4371e940df5a34a3888b2",
      • "enabled": true,
      • "bucket": "string",
      • "prefix": "string"
      },
    • "ms": 0,
    • "wait_ms": 0,
    • "overhead_ms": 0,
    • "lag_ms": 0,
    • "total_ms": 0,
    • "handler_version": "string",
    • "version": "string",
    • "cap_reached": true,
    • "flow_ping_limits": {
      • "id": "5fd4371e940df5a34a3888b2",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "2019-08-24T14:15:22Z"
      },
    • "source_ping_limits": {
      • "id": "5fd4371e940df5a34a3888b2",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "2019-08-24T14:15:22Z"
      },
    • "ping_limit_reached": true,
    • "expires_at": "2019-08-24T14:15:22Z",
    • "module_id": "string",
    • "package_version": "string",
    • "acceptance_criteria": {
      • "rule_set": {
        • "id": "1aacd0",
        • "op": "and",
        • "rules": [
          • {
            • "id": "1aacd0",
            • "lhv": "lead.state",
            • "op": "is equal to",
            • "rhv": "TX",
            • "rule_set": { }
            }
          ]
        },
      • "outcome": "failure",
      • "reason": "string"
      },
    • "step_count": 4,
    • "appended": { },
    • "request": {},
    • "response": {
      • "status": 201,
      • "status_text": "Created",
      • "version": "1.1",
      • "headers": { },
      • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
      • "timestamp": 0
      }
    }
]

List all events for exports

The /events resource is used to query events generated while handling leads. For each lead, one event is generated for each configured flow step that handles the lead. After lead processing completes, a source event is also recorded.

SecurityAPIKey
Request
Request Body schema: application/json

Query parameters

start
string <date-time> (Timestamp)

Return only events that were created at or after this time

end
string <date-time> (Timestamp)

Return only events that were created at or before this time

Array of Binary Rule (object) or Unary Rule (object) (Rule)

Rules to select matching events

include
Array of strings

An array of fields to include. Cannot be used with exclude.

exclude
Array of strings

An array of fields to exclude. Cannot be used with include.

limit
integer [ 1 .. 1000 ]

The maximum number of events to return (maximum limit is 1000, default 100)

sort
string

The results are sorted by date. Use asc to sort by oldest first or desc to sort by newest first. Defaults to desc.

Responses
200

OK

401

Authorization information is missing or invalid.

post/events
Request samples
application/json
{
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "rules": [
    • {
      • "lhv": "lead.state",
      • "op": "is equal to",
      • "rhv": "TX",
      • "rule_set": {
        • "op": "and",
        • "rules": [
          • { }
          ]
        }
      }
    ],
  • "include": [
    • "string"
    ],
  • "exclude": [
    • "string"
    ],
  • "limit": 1,
  • "sort": "string"
}
Response samples
application/json
[
  • {
    • "type": "source",
    • "id": "5fd4371e940df5a34a3888b2",
    • "outcome": "success",
    • "reason": "string",
    • "vars": { },
    • "host": "string",
    • "start_timestamp": 0,
    • "end_timestamp": 0,
    • "firehose": {
      • "credential_id": "5fd4371e940df5a34a3888b2",
      • "enabled": true,
      • "bucket": "string",
      • "prefix": "string"
      },
    • "ms": 0,
    • "wait_ms": 0,
    • "overhead_ms": 0,
    • "lag_ms": 0,
    • "total_ms": 0,
    • "handler_version": "string",
    • "version": "string",
    • "cap_reached": true,
    • "flow_ping_limits": {
      • "id": "5fd4371e940df5a34a3888b2",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "2019-08-24T14:15:22Z"
      },
    • "source_ping_limits": {
      • "id": "5fd4371e940df5a34a3888b2",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "2019-08-24T14:15:22Z"
      },
    • "ping_limit_reached": true,
    • "expires_at": "2019-08-24T14:15:22Z",
    • "module_id": "string",
    • "package_version": "string",
    • "acceptance_criteria": {
      • "rule_set": {
        • "id": "1aacd0",
        • "op": "and",
        • "rules": [
          • {
            • "id": "1aacd0",
            • "lhv": "lead.state",
            • "op": "is equal to",
            • "rhv": "TX",
            • "rule_set": { }
            }
          ]
        },
      • "outcome": "failure",
      • "reason": "string"
      },
    • "step_count": 4,
    • "appended": { },
    • "request": {},
    • "response": {
      • "status": 201,
      • "status_text": "Created",
      • "version": "1.1",
      • "headers": { },
      • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
      • "timestamp": 0
      }
    }
]

Fetch a single event

SecurityAPIKey
Request
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$

ID of the event to get

Example: 5fd4371e940df5a34a3888b2
Responses
200

OK

401

Authorization information is missing or invalid.

get/events/{id}
Request samples
Response samples
application/json
{
  • "id": "5fd4371e940df5a34a3888b2",
  • "outcome": "success",
  • "reason": "string",
  • "vars": { },
  • "host": "string",
  • "start_timestamp": 0,
  • "end_timestamp": 0,
  • "firehose": {
    • "credential_id": "5fd4371e940df5a34a3888b2",
    • "enabled": true,
    • "bucket": "string",
    • "prefix": "string"
    },
  • "ms": 0,
  • "wait_ms": 0,
  • "overhead_ms": 0,
  • "lag_ms": 0,
  • "total_ms": 0,
  • "handler_version": "string",
  • "version": "string",
  • "cap_reached": true,
  • "flow_ping_limits": {
    • "id": "5fd4371e940df5a34a3888b2",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "2019-08-24T14:15:22Z"
    },
  • "source_ping_limits": {
    • "id": "5fd4371e940df5a34a3888b2",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "2019-08-24T14:15:22Z"
    },
  • "ping_limit_reached": true,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "type": "source",
  • "module_id": "string",
  • "package_version": "string",
  • "acceptance_criteria": {
    • "rule_set": {
      • "id": "1aacd0",
      • "op": "and",
      • "rules": [
        • {
          • "id": "1aacd0",
          • "lhv": "lead.state",
          • "op": "is equal to",
          • "rhv": "TX",
          • "rule_set": { }
          }
        ]
      },
    • "outcome": "failure",
    • "reason": "string"
    },
  • "step_count": 4,
  • "appended": { },
  • "request": {},
  • "response": {
    • "status": 201,
    • "status_text": "Created",
    • "version": "1.1",
    • "headers": { },
    • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
    • "timestamp": 0
    }
}

Retrieve statistics on events

The /events/stats resource is used to count events. The event count can be grouped by any field collected with the lead or appended to the lead during flow processing. The API also supports returning results in JSON or CSV using the appropriate MIME type in the Accept header.

SecurityAPIKey
Request
query Parameters
type
string

Convenience option that specifies a filter on event type (source, recipient, filter, feedback-received, or feedback-sent). Can be used multiple times to specify multiple types. (default: source)

Binary Rule (object) or Unary Rule (object) (Rule)

Limit counted events using this rule. Can be used multiple times to specify multiple rules. Each rule must be sent as URL encoded JSON.

group_by
string

Group event counts by unique values of this property. Can be used multiple times to specify multiple properties. (default: none)

interval
string

Groups event counts into sub-timeframes spanning a specified length of time: minutely, hourly, daily, weekly, monthly, yearly (default: none)

timezone
integer

When an interval is specified, this time zone will be used to set the start and end of each interval. Any tz database time zone name (i.e. America/Chicago) or the number of seconds to offset time from UTC (i.e. -18000)

start
string <date-time> (Timestamp)

Count events that were created at or after this time (default: beginning of the day today)

end
string <date-time> (Timestamp)

Count events that were created at or before this time (default: end of the day today)

outcome
string

DEPRECATED: use column instead. The outcome to count (default: success, failure, error). Can be used multiple times to specify multiple types.

object (Event Statistic)

A column to aggregate. Can be used multiple times to specify multiple columns. source-success, source-failure, source-error

by_lead
boolean

Boolean indicating whether to count unique leads or unique events - false counts individual events (default: true)

Responses
200

OK

get/events/stats
Request samples
Response samples
application/json
[
  • {
    • "source-submitted": 0,
    • "source-success": 0,
    • "source-failure": 0,
    • "source-error": 0,
    • "recipient-submitted": 0,
    • "recipient-success": 0,
    • "recipient-failure": 0,
    • "recipient-error": 0,
    • "return-received-submitted": 0,
    • "return-received-success": 0,
    • "return-received-failure": 0,
    • "return-received-error": 0,
    • "return-sent-submitted": 0,
    • "return-sent-success": 0,
    • "return-sent-failure": 0,
    • "return-sent-error": 0,
    • "conversion-received-submitted": 0,
    • "conversion-received-success": 0,
    • "conversion-received-failure": 0,
    • "conversion-received-error": 0,
    • "conversion-sent-submitted": 0,
    • "conversion-sent-success": 0,
    • "conversion-sent-failure": 0,
    • "conversion-sent-error": 0,
    • "ping-submitted": 0,
    • "ping-success": 0,
    • "ping-success-rate": 0,
    • "ping-win-rate": 0,
    • "cost": 0,
    • "revenue": 0,
    • "profit": 0,
    • "cost-per-conversion-received-success": 0,
    • "avg-cost-per-lead": 0,
    • "avg-revenue-per-lead": 0
    }
]

Search leads

The /search/leads resource is used to find leads using full text search. For example, you can search for fred in texas using:

/search/leads?query=fred+tx

Search Criteria

  • pass in the search text using the query parameter: /search/leads?query=fred
  • the query parameter should be URL encoded
  • searching is case-insensitive: FRED and fred will both match Fred
  • you don't have to enter a complete word - searching will match the beginning of words: /search/leads?query=sam will match sam and samantha
  • queries with multiple words like fred tx will match leads that have both fred AND tx
  • to specify an exact phrase (with spaces), use double quotes - "fred tx" will only match that exact text

The search results can be sorted and paginated. There are two query parameter to control sorting: sort_by and sort_dir. The sort_by parameter takes a field name (see list below) and sort_dir is ascending (asc) or descending (desc). By default, the results are sorted by relevance.

There are two query parameters to control paging: from and limit. The from parameter specifies the starting offset of that page in the search results and the limit parameter specifies how many search results to return. From is zero-based so to get the first 10 results, use from=0&limit=10, the second 10 using from=10&limit=10, etc... The maximum limit is 100 at a time, with an overall maximum of 1,000 search results.

Search Results

The search results has the total number of matching leads and an array of hits, where each hit is a matching Lead Search Result. Each lead search result contains basic information about the lead, the latest event for that lead, and highlighting of the matched text.

SecurityAPIKey
Request
query Parameters
query
string

text to search for

sort_by
string

One of the following field names: lead_id, submission_timestamp, first_name, last_name, email, phone_1, phone_2, address_1, city, state, postal_code, reference

Enum: "lead_id" "submission_timestamp" "first_name" "last_name" "email" "phone_1" "phone_2" "address_1" "city" "state" "postal_code" "reference"
sort_dir
string

The sort direction: "asc" or "desc", default is by relevance

Enum: "asc" "desc"
from
integer

The starting offset of leads to return in the matching result set, zero-based

limit
integer

The maximum number of leads to return (maximum is 100, default is 10)

Responses
200

OK

get/search/leads
Request samples
Response samples
application/json
[
  • {
    • "lead_id": "5fd4371e940df5a34a3888b2",
    • "flow_id": "5fd4371e940df5a34a3888b2",
    • "flow_name": "Sales Leads",
    • "source_id": "5fd4371e940df5a34a3888b2",
    • "source_name": "A Corporation",
    • "first_name": "George",
    • "last_name": "Washington",
    • "email": "georgew@gmail.com",
    • "phone_1": "5125551212",
    • "phone_2": "5125552222",
    • "address_1": "123 Main street",
    • "city": "Austin",
    • "postal_code": "78704",
    • "reference": "1990118214561",
    • "state": "TX",
    • "submission_timestamp": "2019-08-24T14:15:22Z",
    • "highlight": { },
    • "latest_event": {
      • "id": "5fd4371e940df5a34a3888b2",
      • "outcome": "success",
      • "reason": "string",
      • "vars": {
        • "price": 0,
        • "purchase_price": 0,
        • "event_id": "5fd4371e940df5a34a3888b2"
        },
      • "host": "string",
      • "start_timestamp": 0,
      • "end_timestamp": 0,
      • "firehose": {
        • "credential_id": "5fd4371e940df5a34a3888b2",
        • "enabled": true,
        • "bucket": "string",
        • "prefix": "string"
        },
      • "ms": 0,
      • "wait_ms": 0,
      • "overhead_ms": 0,
      • "lag_ms": 0,
      • "total_ms": 0,
      • "handler_version": "string",
      • "version": "string",
      • "cap_reached": true,
      • "flow_ping_limits": {
        • "id": "5fd4371e940df5a34a3888b2",
        • "name": "string",
        • "maximum": 0,
        • "duration": 0,
        • "duration_units": "string",
        • "time_zone": "America/New_York",
        • "created_at": "2019-08-24T14:15:22Z"
        },
      • "source_ping_limits": {
        • "id": "5fd4371e940df5a34a3888b2",
        • "name": "string",
        • "maximum": 0,
        • "duration": 0,
        • "duration_units": "string",
        • "time_zone": "America/New_York",
        • "created_at": "2019-08-24T14:15:22Z"
        },
      • "ping_limit_reached": true,
      • "expires_at": "2019-08-24T14:15:22Z",
      • "type": "recipient",
      • "step_id": "string",
      • "caps": [
        • {
          • "id": "5fd4371e940df5a34a3888b2",
          • "type": "volume",
          • "name": "Monthly leads from TX",
          • "maximum": 1200,
          • "duration": 1,
          • "duration_units": "month",
          • "rule_set": {
            • "id": "1aacd0",
            • "op": "and",
            • "rules": [
              • {
                • "id": null,
                • "lhv": null,
                • "op": null,
                • "rhv": null,
                • "rule_set": null
                }
              ]
            },
          • "caps": [
            • { }
            ],
          • "time_zone": "America/New_York",
          • "reason": "string",
          • "created_at": "2020-11-23T11:41:52Z"
          }
        ],
      • "caps_reached": true,
      • "key": "string",
      • "cost": 0,
      • "purchase_price": 0,
      • "sale_price": 0,
      • "revenue": 0,
      • "module_id": "string",
      • "credential": {
        • "id": "5fd4371e940df5a34a3888b2",
        • "name": "string",
        • "type": "user",
        • "package": "string",
        • "created_at": "2019-08-24T14:15:22Z",
        • "updated_at": "2019-08-24T14:15:22Z",
        • "username": "string",
        • "password": "string"
        },
      • "credential_updated": true,
      • "package_version": "string",
      • "rule_set": {
        • "id": "1aacd0",
        • "op": "and",
        • "rules": [
          • {
            • "id": "1aacd0",
            • "lhv": "lead.state",
            • "op": "is equal to",
            • "rhv": "TX",
            • "rule_set": { }
            }
          ]
        },
      • "mappings": [
        • {
          • "id": "1aacd0",
          • "property": "string",
          • "value": "string",
          • "rule_set": {
            • "id": "1aacd0",
            • "op": "and",
            • "rules": [
              • {
                • "id": null,
                • "lhv": null,
                • "op": null,
                • "rhv": null,
                • "rule_set": null
                }
              ]
            }
          }
        ],
      • "pricing": {
        • "override": true,
        • "prices": [
          • {
            • "id": { },
            • "amount": 0,
            • "rule_set": {
              • "id": "1aacd0",
              • "op": "and",
              • "rules": [
                • null
                ]
              }
            }
          ]
        },
      • "transactions": []
      }
    }
]