Leads

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. There are several different kinds of events, each with unique properties.

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

24 character alpha-numeric BSON identifier

type
required
string

Recorded after a source submits a lead to a flow

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

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

module_id
string

The integration module ID configured for the source

package_version
object or null (Acceptance Criteria)

Acceptance criteria specifies the kinds of leads that a source or sources must provide in a flow. Acceptance criteria can be configured at both a flow level and a source level. When a source submits a lead, the flow-level acceptance criteria's rule set is evaluated first, then any source-level acceptance criteria. If the rule sets pass, then the lead is allowed to progress on in the flow. But if either rule set fails, then the source is immediately given a response and no further processing takes place in the flow for that lead.

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

The inbound HTTP request

object

The inbound HTTP response

{
  • "id": "636999a5a28de89048cd16fc",
  • "type": "source",
  • "outcome": "success",
  • "reason": "string",
  • "vars": { },
  • "host": "string",
  • "start_timestamp": 0,
  • "end_timestamp": 0,
  • "firehose": {
    • "credential_id": "string",
    • "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": "6402715c40926f93753580d9",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "string"
    },
  • "source_ping_limits": {
    • "id": "6402715c40926f93753580d9",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "string"
    },
  • "ping_limit_reached": true,
  • "expires_at": "string",
  • "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": "Lead must live in TX"
    },
  • "step_count": 4,
  • "appended": { },
  • "request": {},
  • "response": {
    • "status": 201,
    • "status_text": "Created",
    • "version": "1.1",
    • "headers": {
      • "Content-Type": "application/json",
      • "Accept": "application/json"
      },
    • "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)

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

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

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
[
  • {
    • "id": "636999a5a28de89048cd16fc",
    • "type": "source",
    • "outcome": "success",
    • "reason": "string",
    • "vars": { },
    • "host": "string",
    • "start_timestamp": 0,
    • "end_timestamp": 0,
    • "firehose": {
      • "credential_id": "string",
      • "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": "6402715c40926f93753580d9",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "string"
      },
    • "source_ping_limits": {
      • "id": "6402715c40926f93753580d9",
      • "name": "string",
      • "maximum": 0,
      • "duration": 0,
      • "duration_units": "string",
      • "time_zone": "America/New_York",
      • "created_at": "string"
      },
    • "ping_limit_reached": true,
    • "expires_at": "string",
    • "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": "Lead must live in TX"
      },
    • "step_count": 4,
    • "appended": { },
    • "request": {},
    • "response": {
      • "status": 201,
      • "status_text": "Created",
      • "version": "1.1",
      • "headers": {
        • "Content-Type": "application/json",
        • "Accept": "application/json"
        },
      • "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


 
Responses 
200
OK


401
Authorization information is missing or invalid.


get/events/{id}
Request samples 
Response samples 
application/json
{
  • "id": "636999a5a28de89048cd16fc",
  • "type": "source",
  • "outcome": "success",
  • "reason": "string",
  • "vars": { },
  • "host": "string",
  • "start_timestamp": 0,
  • "end_timestamp": 0,
  • "firehose": {
    • "credential_id": "string",
    • "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": "6402715c40926f93753580d9",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "string"
    },
  • "source_ping_limits": {
    • "id": "6402715c40926f93753580d9",
    • "name": "string",
    • "maximum": 0,
    • "duration": 0,
    • "duration_units": "string",
    • "time_zone": "America/New_York",
    • "created_at": "string"
    },
  • "ping_limit_reached": true,
  • "expires_at": "string",
  • "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": "Lead must live in TX"
    },
  • "step_count": 4,
  • "appended": { },
  • "request": {},
  • "response": {
    • "status": 201,
    • "status_text": "Created",
    • "version": "1.1",
    • "headers": {
      • "Content-Type": "application/json",
      • "Accept": "application/json"
      },
    • "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": "64ace5991aea850ab7f74467",
    • "flow_id": "5fd4371e940df5a34a3888b2",
    • "flow_name": "Sales Leads",
    • "source_id": "64ace4542ff45e6d2bd5f957",
    • "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": "636999a5a28de89048cd16fc",
      • "type": "recipient",
      • "outcome": "success",
      • "reason": "string",
      • "vars": {
        • "price": 0,
        • "purchase_price": 0,
        • "event_id": "636999a5a28de89048cd16fc"
        },
      • "host": "string",
      • "start_timestamp": 0,
      • "end_timestamp": 0,
      • "firehose": {
        • "credential_id": "string",
        • "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": "6402715c40926f93753580d9",
        • "name": "string",
        • "maximum": 0,
        • "duration": 0,
        • "duration_units": "string",
        • "time_zone": "America/New_York",
        • "created_at": "string"
        },
      • "source_ping_limits": {
        • "id": "6402715c40926f93753580d9",
        • "name": "string",
        • "maximum": 0,
        • "duration": 0,
        • "duration_units": "string",
        • "time_zone": "America/New_York",
        • "created_at": "string"
        },
      • "ping_limit_reached": true,
      • "expires_at": "string",
      • "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": "Lead must live in TX"
        },
      • "step_count": 4,
      • "appended": { },
      • "request": {},
      • "response": {
        • "status": 201,
        • "status_text": "Created",
        • "version": "1.1",
        • "headers": {
          • "Content-Type": "application/json",
          • "Accept": "application/json"
          },
        • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
        • "timestamp": 0
        },
      • "step_id": "string",
      • "caps": [
        • {
          • "id": "string",
          • "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,
      • "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,
      • "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": [
        • {
          • "request": {},
          • "response": {
            • "status": 201,
            • "status_text": "Created",
            • "version": "1.1",
            • "headers": {
              • "Content-Type": "application/json",
              • "Accept": "application/json"
              },
            • "body": "{\"outcome\":\"success\",\"lead\":{\"id\":\"63cc6f0e55254d7d1c4c3037\"}}",
            • "timestamp": 0
            },
          • "ms": 0
          }
        ]
      }
    }
]