Reporting

These endpoints return aggregated and per-user data used by the Reporting features of Close. Any fields related to revenue are returned in cents. Any duration values are returned in seconds.

List the predefined metrics used in activity reports.

GET /report/activity/metrics/

These metrics are available to use in the report API below.

Get an activity report.

POST /report/activity/

The activity report returns the organization's metrics per time period (overview report) or user (comparison report).

Every report accepts the following parameters:

• datetime_range: a time range to fetch data for. Either this field or relative_range needs to be specified.
• relative_range: a relative time range to fetch data for. The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time. Either this field or datetime_range needs to be specified.
• query: a query to apply to the report to filter out data. The value of the field is a dictionary with the key type and any type-specific keys. For now only the type saved_search is allowed which takes the extra key saved_search_id to specify the ID of a saved search. This parameter is optional.
• users: a list of user IDs to limit the report results to. This parameter is optional.
• type: the type of the report. The available values are overview and comparison. This parameter is mandatory.
• metrics: a list of metrics (see above) to fetch for the report. This parameter is mandatory.

The report can be requested either in a JSON format or in a CSV file. The format can be specified with the accept header.

Get a report about sent emails grouped by template.

GET /report/sent_emails/{ORGANIZATION_ID}/{?user_id, date_start, date_end}

Get a lead status change report.

GET /report/statuses/lead/{ORGANIZATION_ID}/{?date_start, date_end, query}

The date range is optional. A report may be requested for a specific time period or overall. You can specify either a query or smart_view_id (but not both) to filter leads included in the report.

The following fields are returned (when requesting an overall report, some inapplicable fields will not be returned):

• status_overview: A list of all lead statuses with the following fields:
  • status_id, status_label, status_is_deleted: The ID and label of the status, and whether it was deleted.
  • started: Number of leads in this status at the start of the period.
  • ended: Number of leads in this status at the end of the period.
  • change: The net change of the number of leads during the period (ended minus started).
  • change_percent: The net change of leads in percent.
  • gained: Number of leads that were not in this status at the beginning of the period, but were in this status at the end of the period, i.e. leads that transitioned into this status at some point during the period and stayed in this status at the end of the period.
  • lost: Number of leads that were in this status at the beginning of the period, but were not in this status at the end of the period, i.e. leads that transitioned out of this status at some point during the period and stayed in some other status at the end of the period.
  • entered: Number of leads that entered this status at some point during the period.
  • left: Number of leads that left this status at some point during the period.
  • _queries: A dictionary containing search queries which list the leads for the different states (started, ended, gained, lost, entered, left)
  • _leads_page_urls: A dictionary similar to _queries containing paths to the lead search UI page for the different states.
• status_transitions: A list of all status transitions (aggregated by start/end status) for the given period with the following fields:
  • from_status_id, from_status_label, from_status_is_deleted: The ID and label of the starting status, and whether it was deleted. For created leads, these fields are all null.
  • to_status_id, to_status_label, to_status_is_deleted: The ID and label of the ending status, and whether it was deleted.
  • count: The amount of leads that ever transitioned from the starting status to the ending status during the period.
  • _query: The search query which lists the leads.
  • _leads_page_url: The path to the lead search UI page which lists the leads.
• status_transitions_summary: A list of status transitions (aggregated by start/end status), summarized for the given period. For example, a lead that went from status A to status B, and then from status B to status C in the given period will be counted in the transition from A to C. The fields are the same as those returned in status_transitions.

Get an opportunity status change report.

GET /report/statuses/opportunity/{ORGANIZATION_ID}/{?user_id, date_start, date_end, smart_view_id, query}

The arguments and returned fields are similar to the lead status report (see above), with the following differences:

• Any returned numbers refer to the number of opportunities instead of leads.
• The opportunity status report may optionally be filtered by the opportunity user.
• The returned search queries in the _queries field are wrapped in a nested opportunity query (opportunity(...)) and can be used as a query for the leads API endpoint. To pass the query to the opportunities API endpoint, only the query within the nested clause (in the parentheses) may be supplied.
• In addition to returning paths to the lead search UI page, paths to the opportunity UI page are returned in the _opportunities_page_urls and _opportunities_page_url fields.

Get a custom report for just about any object in Close.

GET /report/custom/{ORGANIZATION_ID}/{?query, x, y, interval, transform_y, group_by, start, end}

This endpoint returns data that allows graphing of arbitrary metrics and is what powers "Explorer" in the UI.

• query is an optional search query filter. When reporting on leads, any regular lead search query may be used. When reporting on activities or opportunities, only properties of the chosen object type may be used. For example, direction:incoming may be used if x starts with email.. Defaults to *, which includes all objects.

• y is made up of the object type and field which is reported on the Y axis. For example the value lead.count (used by default) may be used to graph the number of leads, or a numeric field may be used. Examples: call.duration (for call length), opportunity.value (for value of opportunities).

• x is the field which is reported on the X axis, for example "lead.custom.MRR" or "opportunity.date_created".

• interval: Graph interval, i.e. the precision of the X axis. For time based graphs (x is a date field), one of auto, hour, day, week, month, quarter, year (defaults to auto, which is chosen based on start and end). For graphs with a numeric X axis, an integer number can be specified to indicate the histogram interval (auto by default).

• group_by: Optional field name by which the report will be grouped. When grouping, a separate series will be returned for each group. By default no grouping is applied.

• transform_y: Transformation function that gets applied to the y parameter. One of sum (default), avg, min, or max. Does not apply for .count y values if x is of the same object type.

• start: Date or integer of the start of the X axis range. For dates, defaults to the date of creation of your organization.

• end: Date or integer of the end of the X axis range. For dates, defaults to now.

  To get a full list of fields that can be used, do a GET to /report/custom/fields/. Only the number data type can be used for the y parameter.

Get a funnel report (totals).

POST /report/funnel/opportunity/totals/

The opportunity funnel "totals" report returns the pipeline funnel's metrics for the selected opportunities, aggregated (JSON format only) and per-user (JSON and CSV formats).

Every report accepts the following parameters:

• pipeline: ID of the pipeline defining the funnel statuses.
• type: the type of the report. The available values are created-cohort and active-stage-cohort.
• report_relative_range: a relative time range to fetch data for. The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time.
• report_datetime_range: a time range to fetch data for.
• cohort_relative_range: a relative time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time. Either this field or cohort_datetime_range needs to be specified for created-cohort reports. Its value will be ignored for active-stage-cohort reports.
• cohort_datetime_range: a time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. Either this field or cohort_relative_range needs to be specified for created-cohort reports. Its value will be ignored for active-stage-cohort reports.
• compared_relative_range: a relative time range to fetch comparison data for. Only allowed in combination with report_relative_range (for active-stage-cohort reports) or cohort_relative_range (for craeted-cohort reports). The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time.
• compared_datetime_range: a relative time range to fetch comparison data for. Only allowed in combination with report_datetime_range (for active-stage-cohort reports) or cohort_datetime_range (for created-cohort reports). The allowed values are: same-days-last-week, same-days-last-month, same-days-last-quarter, same-days-last-year.
• compared_custom_range: a time range to fetch comparison data for.
• query: a query to apply to the report to filter out data. The value of the field is a dictionary with the key type and any type-specific keys. For now only the type saved_search is allowed which takes the extra key saved_search_id to specify the ID of a saved search. This parameter is optional.
• users: a list of user IDs or group IDs to limit the report results to. When it's empty, the report will include all the available users. This parameter is optional.

The report can be requested either in JSON format or in CSV format. The format can be specified with the accept header.

In JSON format, it includes aggregated and per-user data. When requested in CSV format, it includes only per-user data.

When compared_datetime_range, compared_relative_range, or compared_custom_range are used, the report returned is the compared one, not the base one.

Get a funnel report (stages).

POST /report/funnel/opportunity/stages/

The opportunity funnel "stages" report returns the pipeline funnel's metrics for the selected opportunities, aggregated (JSON format only) and per-user (JSON and CSV formats).

Every report accepts the following parameters:

• pipeline: ID of the pipeline defining the funnel statuses.
• type: the type of the report. The available values are created-cohort and active-stage-cohort.
• report_relative_range: a relative time range to fetch data for. The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time.
• report_datetime_range: a time range to fetch data for.
• cohort_relative_range: a relative time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time. Either this field or cohort_datetime_range needs to be specified for created-cohort reports. Its value will be ignored for active-stage-cohort reports.
• cohort_datetime_range: a time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. Either this field or cohort_relative_range needs to be specified for created-cohort reports. Its value will be ignored for active-stage-cohort reports.
• compared_relative_range: a relative time range to fetch comparison data for. Only allowed in combination with report_relative_range (for active-stage-cohort reports) or cohort_relative_range (for craeted-cohort reports). The allowed values are: today, this-week, this-month, this-quarter, this-year, yesterday, last-week, last-month, last-quarter, last-year, and all-time.
• compared_datetime_range: a relative time range to fetch comparison data for. Only allowed in combination with report_datetime_range (for active-stage-cohort reports) or cohort_datetime_range (for created-cohort reports). The allowed values are: same-days-last-week, same-days-last-month, same-days-last-quarter, same-days-last-year.
• compared_custom_range: a time range to fetch comparison data for.
• query: a query to apply to the report to filter out data. The value of the field is a dictionary with the key type and any type-specific keys. For now only the type saved_search is allowed which takes the extra key saved_search_id to specify the ID of a saved search. This parameter is optional.
• users: a list of user IDs or group IDs to limit the report results to. When it's empty, the report will include all the available users. This parameter is optional.

The report can be requested either in JSON format or in CSV format. The format can be specified with the accept header.

In JSON format, it includes aggregated and per-user data. When requested in CSV format, it includes only per-user data.

When compared_datetime_range, compared_relative_range, or compared_custom_range are used, the report returned is the compared one, not the base one.