openapi: 3.1.0 info: title: API Endpoints subpackage_activities subpackage_reporting API version: 1.0.0 servers: - url: https://api.close.com/api/v1 tags: - name: subpackage_reporting paths: /report/activity/: post: operationId: get-activity summary: Get an activity report description: "The activity report returns the organization's metrics per time period (**overview** report) or user (**comparison** report).\n\nEvery report accepts the following parameters:\n\n* `datetime_range`: a time range to fetch data for. Either this field or `relative_range` needs to be specified.\n* `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.\n* `query`: a query to apply to the report to filter out data.\n 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*.\n* `users`: a list of user IDs to limit the report results to. This parameter is *optional*.\n* `type`: the type of the report. The available values are `overview` and `comparison`.\n This parameter is *mandatory*.\n* `metrics`: a list of metrics (see [above](#list-the-predefined-metrics-used-in-activity-reports)) to fetch for the report. This parameter is *mandatory*.\n\nThe report can be requested either in a JSON format or in a CSV file. The format can be specified with the `accept` header." tags: - subpackage_reporting parameters: - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getActivity_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type requestBody: content: application/json: schema: description: Any type /report/activity/metrics/: get: operationId: list-activity-metrics summary: List the predefined metrics used in activity reports description: List available metrics that can be used in activity reports. tags: - subpackage_reporting parameters: - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_listActivityMetrics_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type /report/custom/{org_id}/: get: operationId: get-custom summary: Get custom report (Explorer) description: "This endpoint returns data that allows graphing of arbitrary metrics and is what powers \"Explorer\" in the UI.\n\n - `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.\n - `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).\n - `x` is the field which is reported on the X axis, for example \"lead.custom.MRR\" or \"opportunity.date_created\".\n - `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).\n - `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.\n - `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.\n - `start`: Date or integer of the start of the X axis range. For dates, defaults to the date of creation of your organization.\n - `end`: Date or integer of the end of the X axis range. For dates, defaults to now.\n\n 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." tags: - subpackage_reporting parameters: - name: org_id in: path required: true schema: type: string - name: query in: query required: false schema: type: string - name: x in: query required: false schema: type: string - name: y in: query required: false schema: type: string - name: group_by in: query required: false schema: type: string - name: transform_y in: query required: false schema: $ref: '#/components/schemas/ReportCustomOrgIdGetParametersTransformY' - name: interval in: query required: false schema: type: string - name: start in: query required: false schema: type: string - name: end in: query required: false schema: type: string - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getCustom_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type /report/funnel/opportunity/stages/: post: operationId: get-funnel-stages summary: Get a funnel report (stages) description: "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).\n\nEvery report accepts the following parameters:\n\n* `pipeline`: ID of the pipeline defining the funnel statuses.\n* `type`: the type of the report. The available values are `created-cohort` and `active-stage-cohort`.\n* `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`.\n* `report_datetime_range`: a time range to fetch data for.\n* `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.\n* `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.\n* `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 `created-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`.\n* `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`.\n* `compared_custom_range`: a time range to fetch comparison data for.\n* `query`: a query to apply to the report to filter out data.\n 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*.\n* `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*.\n\nThe report can be requested either in JSON format or in CSV format. The format can be specified with the `accept` header.\n\nIn JSON format, it includes aggregated and per-user data. When requested in CSV format, it includes only per-user data.\n\nWhen `compared_datetime_range`, `compared_relative_range`, or `compared_custom_range` are used, the report returned is the compared one, not the base one." tags: - subpackage_reporting parameters: - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getFunnelStages_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type requestBody: content: application/json: schema: description: Any type /report/funnel/opportunity/totals/: post: operationId: get-funnel-totals summary: Get a funnel report (totals) description: "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).\n\nEvery report accepts the following parameters:\n\n* `pipeline`: ID of the pipeline defining the funnel statuses.\n* `type`: the type of the report. The available values are `created-cohort` and `active-stage-cohort`.\n* `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`.\n* `report_datetime_range`: a time range to fetch data for.\n* `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.\n* `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.\n* `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 `created-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`.\n* `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`.\n* `compared_custom_range`: a time range to fetch comparison data for.\n* `query`: a query to apply to the report to filter out data.\n 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*.\n* `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*.\n\nThe report can be requested either in JSON format or in CSV format. The format can be specified with the `accept` header.\n\nIn JSON format, it includes aggregated and per-user data. When requested in CSV format, it includes only per-user data.\n\nWhen `compared_datetime_range`, `compared_relative_range`, or `compared_custom_range` are used, the report returned is the compared one, not the base one." tags: - subpackage_reporting parameters: - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getFunnelTotals_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type requestBody: content: application/json: schema: description: Any type /report/sent_emails/{org_id}/: get: operationId: get-sent-emails summary: Get sent emails report tags: - subpackage_reporting parameters: - name: org_id in: path required: true schema: type: string - name: date_start in: query required: false schema: type: string - name: date_end in: query required: false schema: type: string - name: user_id in: query required: false schema: type: string - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getSentEmails_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type /report/statuses/lead/{org_id}/: get: operationId: get-lead-statuses summary: Get lead status change report description: "Get a lead status change report.\n\nThe date range is optional. A report may be requested\nfor a specific time period or overall. You can specify\neither a `query` or `smart_view_id` (but not both) to\nfilter leads included in the report.\n\nThe following fields are returned (when requesting an\noverall report, some inapplicable fields will not be\nreturned):\n\n* `status_overview`: A list of all statuses with:\n * `status_id`, `status_label`,\n `status_is_deleted`: The ID and label of the\n status, and whether it was deleted.\n * `started`: Number of leads in this status at\n the start of the period.\n * `ended`: Number in this status at the end.\n * `change`: Net change during the period\n (`ended` minus `started`).\n * `change_percent`: Net change in percent.\n * `gained`: Number that were not in this status\n at the beginning but were at the end.\n * `lost`: Number that were in this status at the\n beginning but were not at the end.\n * `entered`: Number that entered this status at\n some point during the period.\n * `left`: Number that left this status at some\n point during the period.\n * `_queries`: A dictionary containing search\n queries for the different states (`started`,\n `ended`, `gained`, `lost`, `entered`, `left`).\n * `_leads_page_urls`: A dictionary containing\n paths to the lead search UI page.\n* `status_transitions`: A list of all status\n transitions (aggregated by start/end status) for\n the given period with:\n * `from_status_id`, `from_status_label`,\n `from_status_is_deleted`: Starting status\n (null for created leads).\n * `to_status_id`, `to_status_label`,\n `to_status_is_deleted`: Ending status.\n * `count`: The number that transitioned.\n * `_query`: The search query for those records.\n * `_leads_page_url`: Path to the search UI page.\n* `status_transitions_summary`: Status transitions\n summarized for the period. E.g. a lead that went\n A→B→C is counted as A→C." tags: - subpackage_reporting parameters: - name: org_id in: path required: true schema: type: string - name: date_start in: query required: false schema: type: string - name: date_end in: query required: false schema: type: string - name: query in: query required: false schema: type: string - name: smart_view_id in: query required: false schema: type: string - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getLeadStatuses_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type /report/statuses/opportunity/{org_id}/: get: operationId: get-opportunity-statuses summary: Get opportunity status change report description: "Get an opportunity status change report.\n\nThe date range is optional. A report may be requested\nfor a specific time period or overall. You can specify\neither a `query` or `smart_view_id` (but not both) to\nfilter opportunities included in the report. The\nreport may optionally be filtered by the opportunity\nuser.\n\nThe following fields are returned (when requesting an\noverall report, some inapplicable fields will not be\nreturned):\n\n* `status_overview`: A list of all statuses with:\n * `status_id`, `status_label`,\n `status_is_deleted`: The ID and label of the\n status, and whether it was deleted.\n * `started`: Number of opportunities in this\n status at the start of the period.\n * `ended`: Number in this status at the end.\n * `change`: Net change during the period\n (`ended` minus `started`).\n * `change_percent`: Net change in percent.\n * `gained`: Number that were not in this status\n at the beginning but were at the end.\n * `lost`: Number that were in this status at the\n beginning but were not at the end.\n * `entered`: Number that entered this status at\n some point during the period.\n * `left`: Number that left this status at some\n point during the period.\n * `_queries`: A dictionary containing search\n queries for the different states (`started`,\n `ended`, `gained`, `lost`, `entered`, `left`).\n Search queries are wrapped in a nested\n `opportunity(...)` clause. To pass the query\n to the opportunities API endpoint, use only\n the query within the parentheses.\n * `_leads_page_urls`: A dictionary containing\n paths to the lead search UI page.\n * `_opportunities_page_urls`: A dictionary\n containing paths to the opportunity UI page.\n* `status_transitions`: A list of all status\n transitions (aggregated by start/end status) for\n the given period with:\n * `from_status_id`, `from_status_label`,\n `from_status_is_deleted`: Starting status\n (null for created opportunities).\n * `to_status_id`, `to_status_label`,\n `to_status_is_deleted`: Ending status.\n * `count`: The number that transitioned.\n * `_query`: The search query for those records.\n * `_leads_page_url`: Path to the search UI page.\n * `_opportunities_page_url`: Path to the\n opportunity UI page.\n* `status_transitions_summary`: Status transitions\n summarized for the period. E.g. an opportunity\n that went A→B→C is counted as A→C." tags: - subpackage_reporting parameters: - name: org_id in: path required: true schema: type: string - name: date_start in: query required: false schema: type: string - name: date_end in: query required: false schema: type: string - name: query in: query required: false schema: type: string - name: smart_view_id in: query required: false schema: type: string - name: user_id in: query required: false schema: type: string - name: Authorization in: header description: Use your API key as the username and leave the password empty. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/reporting_getOpportunityStatuses_Response_200' '400': description: Bad request content: application/json: schema: description: Any type '401': description: Unauthorized content: application/json: schema: description: Any type '404': description: Not found content: application/json: schema: description: Any type components: schemas: reporting_getActivity_Response_200: type: object properties: {} description: Empty response body title: reporting_getActivity_Response_200 reporting_getSentEmails_Response_200: type: object properties: {} description: Empty response body title: reporting_getSentEmails_Response_200 reporting_listActivityMetrics_Response_200: type: object properties: {} description: Empty response body title: reporting_listActivityMetrics_Response_200 reporting_getFunnelTotals_Response_200: type: object properties: {} description: Empty response body title: reporting_getFunnelTotals_Response_200 reporting_getCustom_Response_200: type: object properties: {} description: Empty response body title: reporting_getCustom_Response_200 reporting_getFunnelStages_Response_200: type: object properties: {} description: Empty response body title: reporting_getFunnelStages_Response_200 ReportCustomOrgIdGetParametersTransformY: type: string enum: - sum - avg - min - max title: ReportCustomOrgIdGetParametersTransformY reporting_getOpportunityStatuses_Response_200: type: object properties: {} description: Empty response body title: reporting_getOpportunityStatuses_Response_200 reporting_getLeadStatuses_Response_200: type: object properties: {} description: Empty response body title: reporting_getLeadStatuses_Response_200 securitySchemes: ApiKeyAuth: type: http scheme: basic description: Use your API key as the username and leave the password empty. OAuth2: type: http scheme: bearer