Reporting API endpoints
Use the Reporting API endpoints to manage the email recipient lists for the Helix Dashboard reports. Before you run an endpoint, make sure that you authenticate the API request and log in as an administrator.
Warning
Important
For details on parameters used in the Example Value tab of this API endpoints, click the Schema tab and expand the required parameter.
openapi: 3.0.0
components:
schemas:
AllReportConfigurationsRecipientResponse:
type: object
properties:
id:
type: integer
format: int64
description: Unique ID for the recipient list.
example: 1
description:
type: string
description: Description of the recipient list.
example: System admin recipient
name:
type: string
description: Name of the recipient list.
example: Dominick Cobb
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@system.com
- mal@system.com
AllReportConfigurationsReportConfigurationResponse:
type: object
properties:
report_configuration_id:
type: integer
format: int64
description: Unique ID of the report configuration
name:
type: string
maxLength: 180
description: Name of the report configuration
description:
type: string
description: Description of the report configuration
local_recipients:
description: List of local recipients lists
type: array
items:
$ref: '#/components/schemas/AllReportConfigurationsRecipientResponse'
required:
- name
AllReportConfigurationsResponse:
type: object
properties:
status_code:
type: integer
format: int32
description: The status code of the response.
status_message:
type: string
description: The status message of the response.
report_configurations:
description: List of report configurations
type: array
items:
$ref: >-
#/components/schemas/AllReportConfigurationsReportConfigurationResponse
DomainLevel:
type: string
enum:
- 'NO'
- LEVEL1
- LEVEL2
- LEVEL3
- LEVEL4
ReportDate:
type: object
properties:
year:
type: integer
format: int32
month:
type: integer
format: int32
date:
type: integer
format: int32
required:
- year
- month
- date
TimeRange:
type: object
properties:
from:
$ref: '#/components/schemas/ReportDate'
to:
$ref: '#/components/schemas/ReportDate'
Date:
type: object
properties:
year:
type: integer
format: int32
month:
type: integer
format: int32
day:
type: integer
format: int32
required:
- year
- month
- day
ReportConfiguration:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
maxLength: 180
description:
type: string
template_id:
type: string
app_id:
type: integer
format: int64
include_domains:
$ref: '#/components/schemas/DomainLevel'
time_filter:
type: integer
format: int64
time_range:
$ref: '#/components/schemas/TimeRange'
format:
type: array
items:
type: string
reporter_task:
type: integer
format: int64
creation_date:
$ref: '#/components/schemas/Date'
user_id:
type: integer
format: int64
email_include_attachment:
type: array
description: >-
Specifies whether to attach reports in the email. Supported values:
NONE, ALL. Use ['ALL'] to attach reports for all available report
formats, or ['NONE'] to exclude attachments. If no value is provided
attachment will be excluded.
example: '[''NONE''], [''ALL'']'
items:
type: string
email_subject:
type: string
description: >-
Specifies the subject of the email. You can include text and use
available macros: %REPNAME% (report name), %GENDATE% (generation
date), and %DOMAINNAME% (domain name) to dynamically populate the
subject line.
example: '%REPNAME% - %GENDATE% - Domain: %DOMAINNAME%'
email_include_downloadlink:
type: array
description: >-
Specifies whether to include download links in the email. Supported
values: NONE, ALL. Use 'ALL' to include download links for all
available report formats, or 'NONE' to exclude them. If no value is
provided download links will be excluded.
example: '[''NONE''], [''ALL'']'
items:
type: string
email_enabled:
type: boolean
description: Indicates whether email sending is enabled. Default value is false
local_recipients:
type: array
items:
$ref: '#/components/schemas/ReportConfigurationRecipient'
required:
- name
ReportConfigurationRecipient:
type: object
properties:
id:
type: integer
format: int64
description: Unique identifier for the recipient list.
example: 1
description:
type: string
description: Description of the recipient list.
example: Most skilled extractor
name:
type: string
description: Name of the recipient list.
example: Dominick Cobb
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@inception.com
- mal@inception.com
reportConfiguration:
$ref: '#/components/schemas/ReportConfiguration'
description: Reference to the associated report configuration.
ReportConfigurationResponse:
type: object
properties:
status_code:
type: integer
format: int32
description: The status code of the response.
status_message:
type: string
description: The status message of the response.
report_configuration:
$ref: '#/components/schemas/ReportConfiguration'
required:
- status_code
- status_message
ApiError:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
transient:
type: boolean
title: ApiError
description: representation of an error message
LocalRecipientRequest:
type: object
properties:
name:
type: string
description: Name of the recipient list.
example: Sales department
description:
type: string
description: Description of the recipient list.
example: Recipient list for sales department
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@example.com
- mal@system.com
required:
- name
Recipient:
type: object
properties:
id:
type: integer
format: int64
description: Unique ID of the recipient list.
example: 1
description:
type: string
description: Description of the recipient list.
example: System admin recipient
name:
type: string
description: Name of the recipient list.
example: Dominick Cobb
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@system.com
- mal@system.com
report_configuration_id:
type: integer
format: int64
description: Unique ID of the report configuration
required:
- name
SystemRecipient:
type: object
properties:
id:
type: integer
format: int64
description: Unique ID of the recipient list.
example: 1
description:
type: string
description: Description of the recipient list.
example: System admin recipient
name:
type: string
description: Name of the recipient list.
example: Dominick Cobb
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@system.com
- mal@system.com
required:
- name
ReportRequestData:
type: object
properties:
report_configuration:
type: integer
format: int64
description: Report configuration ID.
example: 12345
appid:
type: integer
format: int64
description: Application ID.
example: 67890
required:
- report_configuration
ReportGenerateResponse:
type: object
properties:
status_code:
type: integer
format: int32
description: The status code of the response.
status_message:
type: string
description: The status message of the response.
report_messages:
type: object
additionalProperties:
type: array
items:
type: string
description: List of report messages.
error_messages:
type: object
additionalProperties:
type: array
items:
type: string
description: List of error messages.
required:
- status_code
- status_message
DeleteRecipientsRequest:
type: object
properties:
ids:
type: array
items:
type: integer
format: int64
description: Array of recipient list IDs to be deleted.
example:
- 12
- 13
- 14
required:
- ids
DeleteRecipientsResponse:
type: object
properties:
deleted_ids:
description: List of deleted recipient list IDs
type: array
items:
type: integer
format: int64
example:
- 12
- 13
ids_not_found:
description: List of recipient list IDs that are not found
type: array
items:
type: integer
format: int64
example:
- 14
CreateUpdateRecipientRequest:
type: object
properties:
description:
type: string
description: Description of the recipient list.
example: System admin recipient
name:
type: string
description: Name of the recipient list.
example: Dominick Cobb
domains:
type: array
items:
type: integer
format: int64
description: List of domain IDs associated with the recipient list.
example:
- 101
- 102
emails:
type: array
items:
type: string
format: email
description: List of email addresses associated with the recipient list.
example:
- cobb@system.com
- mal@system.com
required:
- name
DeleteRecipientEmailRequest:
type: object
properties:
email:
type: string
format: email
description: Email address
example: teddy_daniels@example.com
ids:
type: array
items:
type: integer
format: int64
description: List of recipient list IDs. if this field is empty, the email address is removed from all recipient Lists.
required:
- email
RecipientsEmailsResponse:
type: object
properties:
name:
type: string
description: Recipient list name
example: Joseph Cooper
id:
type: integer
format: int64
description: Recipient list ID
example: 0
ReplaceRecipientEmailRequest:
type: object
properties:
old_email:
type: string
format: email
description: Existing email address to be replaced
example: Leon@example.com
new_email:
type: string
format: email
description: New email address to replace with
example: mathilda@example.com
ids:
type: array
items:
type: integer
format: int64
description: List of recipient list IDs. If this field is empty, the email address is replaced in all recipient lists.
required:
- old_email
- new_email
AddEmailToRecipientRequest:
type: object
properties:
email:
type: string
format: email
description: New email address to be added
example: teddy_daniels@example.com
ids:
type: array
items:
type: integer
format: int64
description: List of recipient list IDs. If this field is empty, the email address is added to all recipient lists.
required:
- email
security:
- BearerAuth: []
tags:
- name: Configuration
description: Helix Dashboard Report Configuration
- name: Recipients
description: Helix Dashboard Report Recipients list
paths:
/opt/api/v1/reporting/configuration:
get:
tags:
- Configuration
summary: Get all the Helix Dashboard report configurations
description: Retrieve all Helix Dashboard report configurations
operationId: getAllReportConfigurations
x-permissions:
- admin.admin_section_edit
- admin.admin_section_read
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AllReportConfigurationsResponse'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'/opt/api/v1/reporting/configuration/{report_configuration_id}/recipients':
post:
tags:
- Configuration
summary: Create a local recipient list
description: Create a local recipient list for the Helix Dashboard report.
operationId: createLocalRecipient
x-permissions:
- admin.admin_section_edit
parameters:
- name: report_configuration_id
in: path
description: Unique ID of the report configuration
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocalRecipientRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Recipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'/opt/api/v1/reporting/configuration/{report_configuration_id}/recipients/{id}':
put:
tags:
- Configuration
summary: Update the local recipient list
description: Update the local recipient list. This action overrides the existing recipients list. The fields not provided in the request body are set to null.
operationId: updateLocalRecipient
x-permissions:
- admin.admin_section_edit
parameters:
- name: report_configuration_id
in: path
description: Unique ID of the report configuration
required: true
schema:
type: integer
format: int64
- name: id
in: path
description: Unique ID of the recipient list
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocalRecipientRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Recipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
/opt/api/v1/reporting/recipients:
get:
tags:
- Recipients
summary: Get all the recipient lists
description: Retrieve all Helix Dashboard report recipient lists
operationId: getRecipients
x-permissions:
- admin.admin_section_edit
- admin.admin_section_read
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Recipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
delete:
tags:
- Recipients
description: Delete the recipient lists
summary: Delete the recipient lists
operationId: deleteRecipients
x-permissions:
- admin.admin_section_edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRecipientsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRecipientsResponse'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
/opt/api/v1/reporting/recipients/system:
get:
tags:
- Recipients
summary: Get the global recipient lists
description: Retrieve the global recipient lists of the Helix Dashboard reports
operationId: getSystemRecipients
x-permissions:
- admin.admin_section_edit
- admin.admin_section_read
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SystemRecipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
post:
tags:
- Recipients
summary: Create a global recipient list
description: Create a global recipient list for the Helix Dashboard report
operationId: createSystemRecipient
x-permissions:
- admin.admin_section_edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateRecipientRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SystemRecipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'/opt/api/v1/reporting/recipients/system/{id}':
put:
tags:
- Recipients
summary: Update the global recipient list
description: Update the global recipient list. This action overrides the existing recipients list. The fields not provided in the request body are set to null.
operationId: updateSystemRecipient
x-permissions:
- admin.admin_section_edit
parameters:
- name: id
in: path
description: Unique ID of the recipient list
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateRecipientRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SystemRecipient'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
/opt/api/v1/reporting/recipients/removeEmail:
post:
tags:
- Recipients
summary: Remove the email address from the recipient lists
description: >-
Removes the existing email address from the recipient list. if the ids field is empty,
the email address is removed from all recipient lists.
operationId: deleteEmailAddress
x-permissions:
- admin.admin_section_edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRecipientEmailRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecipientsEmailsResponse'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
/opt/api/v1/reporting/recipients/replaceEmail:
post:
tags:
- Recipients
summary: Replace the existing email address
description: >-
Replace the existing email with a new email address in the recipient list. If the ids field is empty, the email address is replaced in all recipient lists.
operationId: replaceEmailAddress
x-permissions:
- admin.admin_section_edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceRecipientEmailRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecipientsEmailsResponse'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
/opt/api/v1/reporting/recipients/addEmail:
post:
tags:
- Recipients
summary: Add an email address to the recipient lists
description: Add a new email address to the recipient lists.
operationId: addEmailAddress
x-permissions:
- admin.admin_section_edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddEmailToRecipientRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecipientsEmailsResponse'
'400':
description: Bad Request
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
'405':
description: Method Not Allowed
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'
x-exception-class:
- org.springframework.web.HttpRequestMethodNotSupportedException
'500':
description: Internal Server Error
content:
'*/*':
schema:
$ref: '#/components/schemas/ApiError'