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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
        • "op": "is equal to",
        • "rhv": null
        }
      ],
    • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
      • "op": "is equal to",
      • "rhv": null
      }
    ],
  • "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": null,
        • "op": "is equal to",
        • "rhv": null
        }
      ],
    • "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": null,
        • "op": "is equal to",
        • "rhv": null
        }
      ],
    • "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": [
    • { }
    ]
}