Reports

Report

A report is a named definition of criteria (columns, rules, group_bys) which is stored. A stored report can be run for a given timeframe, producing the report results. The results are a count of the events for each column in that timeframe that match the rules and which are optionally grouped by event properties.

Reports can be shared outside LeadConduit such that anyone who has the URL to the shared report can view it without authentication. Each shared report URL contains a generated, unique, unguessable token, which is stored as a property in the report definition. To create the token for a report, use the share endpoint. To stop sharing a report, use the unshare endpoint, which will clear the token.'

name
string

required name of the report

description
string

optional extra description

Array of objects (Report Column)

Array of report columns

Array of objects (ReportRule)

rules to match events to include

group_by
Array of strings

group results by these event properties

token
string

identifier used for sharing

created_at
string <date-time> (Timestamp)

Time report was created

updated_at
string <date-time> (Timestamp)

Time report was last updated

{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

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
    }
]
List all reports
Get the list of all reports.


SecurityAPIKey 
Responses 
200
OK


get/reports
Request samples 
Response samples 
application/json
[
  • {
    • "name": "string",
    • "description": "string",
    • "columns": [
      • {
        • "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
        }
      ],
    • "rules": [
      • {
        • "lhv": "string",
        • "op": "is equal to",
        • "rhv": "string"
        }
      ],
    • "group_by": [
      • "string"
      ],
    • "token": "string",
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]
Create a new report
Create a new report, adding it to the list of all reports in the account.


SecurityAPIKey 
Request 
Request Body schema: application/json
required
Create a new Report


name
string
required name of the report


 
description
string
optional extra description


 
Array of objects (Report Column) 
Array of report columns


 
Array of objects (ReportRule) 
rules to match events to include


 
group_by
Array of strings
group results by these event properties


 
token
string
identifier used for sharing


 
Responses 
201
created


post/reports
Request samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Fetch a single report
Get the report definition for an individual report. The parameter can be
a report id, which requires passing the api_key or a report token, which
does not.


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID or token of the report to fetch


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


get/reports/{id}
Request samples 
Response samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Update an existing report
Update an existing report. Note that the token cannot be updated with
this call. Use the /share endpoint to generate a new token and /unshare
to clear it.


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID or token of the report to fetch


 
 Example:  5fd4371e940df5a34a3888b2
Request Body schema: application/json
required
Update an existing report


name
string
required name of the report


 
description
string
optional extra description


 
Array of objects (Report Column) 
Array of report columns


 
Array of objects (ReportRule) 
rules to match events to include


 
group_by
Array of strings
group results by these event properties


 
token
string
identifier used for sharing


 
Responses 
200
created


put/reports/{id}
Request samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Delete a report
Delete an existing report.


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID or token of the report to delete


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


delete/reports/{id}
Request samples 
Response samples 
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    • {
      • "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
      }
    ],
  • "rules": [
    • {
      • "lhv": "string",
      • "op": "is equal to",
      • "rhv": "string"
      }
    ],
  • "group_by": [
    • "string"
    ],
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Fetch a report's token
Share a report by generating a new token for a report. Once the token is
retrieved, you can use it in place of the ID in the /reports/:id
endpoint.


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


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


put/reports/{id}/share
Request samples 
Response samples 
application/json
{
  • "token": "string"
}
Clear's a reports share token
Unshare a report by clearing the report's token.


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


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


put/reports/{id}/unshare
Request samples 
Response samples 
application/json
{
  • "token": null
}
Create a report without saving it
Create a report but don't save it. The report definition is provided in
the post body and the time range is provided as query parameters.


SecurityAPIKey 
Request 
query Parameters
start
required
string <date-time>  (Timestamp) 
limit events counted in report to those recorded at or after this time


 
end
required
string <date-time>  (Timestamp) 
limit events counted in report to those recorded at or before this
time


 
required
Array of objects (Report Column) 
Array of report columns to display


 
Responses 
200
OK


post/reports/preview
Request samples 
Response samples 
application/json
[
  • {
    • "name": "string",
    • "description": "string",
    • "columns": [
      • {
        • "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
        }
      ],
    • "rules": [
      • {
        • "lhv": "string",
        • "op": "is equal to",
        • "rhv": "string"
        }
      ],
    • "group_by": [
      • "string"
      ],
    • "token": "string",
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]
Run a report
Run a report that was previously created. The parameter can be an id or
token. The time range is provided as query parameters.


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID or token of the report to run


 
 Example:  5fd4371e940df5a34a3888b2
query Parameters
start
required
string <date-time>  (Timestamp) 
limit events counted in report to those recorded at or after this time


 
end
required
string <date-time>  (Timestamp) 
limit events counted in report to those recorded at or before this
time


 
Responses 
200
OK


get/reports/{id}/run
Request samples 
Response samples 
application/json
[
  • {
    • "name": "string",
    • "description": "string",
    • "columns": [
      • {
        • "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
        }
      ],
    • "rules": [
      • {
        • "lhv": "string",
        • "op": "is equal to",
        • "rhv": "string"
        }
      ],
    • "group_by": [
      • "string"
      ],
    • "token": "string",
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]
Get report metadata
Get the metadata for a report that was shared.


SecurityAPIKey 
Request 
path Parameters
token
required
string (ID) ^[0-9a-fA-F]{24}$
Token of the report to retrieve metadata for


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


get/reports/{token}/meta
Request samples 
Response samples 
application/json
{
  • "token": "string",
  • "account_name": "string",
  • "vars": [
    • { }
    ],
  • "flows": [
    • { }
    ],
  • "entities": [
    • { }
    ]
}