# Create a report

Creates a report definition and, unless it is scheduled, immediately queues it
for generation - so a 201 means the report exists, not that the file is ready.
Poll the report until status becomes completed, then use the download endpoint.
A scheduled report is stored with status scheduled and is not run now.
account_id and user_id are taken from the caller and cannot be set from the
request; a value sent for either is overwritten. The response is the same shape
as reading the report, so a follow-up read is not needed.
Invalid input returns a 422 identifying the fields at fault. Some report types
require more than the fields below - the inventory bundle type also requires
meta.bundle_template_id, for instance.
Sending _options.save_as_template also saves the report's type, category,
filters, columns, sorting, media, sub-account and file-type settings as a
reusable report template. It requires the report:template:create permission and
is silently skipped without it.

Endpoint: POST /api/v2/report
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `report_type_id` (integer, required)
    The kind of data the report extracts, from the report type list. Determines which columns and filters are available. Treat it as fixed once the report exists: the update endpoint accepts the field, but changing the type of an existing report is not supported.

  - `name` (string, required)
    Display name for the report, up to 255 characters. Also used as the report template name when _options.save_as_template is set on create.

  - `file_type` (string, required)
    Output format of the generated file: xlsx or csv.

  - `filters` (array)
    Conditions restricting which records the report includes, as groups of {attribute, operator, value} objects. Rows missing an attribute or operator are dropped on save rather than rejected, so a report can come back with fewer filters than were sent.

  - `sorting` (array)
    Order to output rows in, as a list of {field, direction} objects where direction is asc or desc. Only sortable columns of the report's primary entity are applied; anything else is ignored.

  - `columns` (array, required)
    The columns to output, in order, as objects carrying at least a value such as "[user.email]" plus its name and label. Required, and limited to 60 columns of which at most 55 may be custom fields.

  - `with_media` (boolean)
    Whether to deliver the report as a zip containing the uploaded files its rows reference, rather than the spreadsheet on its own.

  - `with_subaccounts` (boolean)
    Whether to include records belonging to accounts below this one in the hierarchy.

  - `is_scheduled` (boolean)
    Whether the report runs on a schedule instead of immediately. Setting it makes the schedule fields required, and is capped by the account's max scheduled report limit. Leaving it false queues the report for generation as soon as the request returns, and clears any schedule already stored.

  - `start_date` (string)
    First date the schedule runs, as YYYY-MM-DD. Required when is_scheduled is true.

  - `start_time` (string)
    Time of day the schedule runs, as HH:MM in the report's timezone. Required when is_scheduled is true.

  - `end_date` (string)
    Date the schedule stops running, as YYYY-MM-DD. Required when is_scheduled is true.

  - `timezone` (string)
    Timezone the schedule's dates and times are interpreted in, as a tz database name such as Australia/Melbourne. Required when is_scheduled is true; defaults to the account's timezone.

  - `repeat` (string)
    How often the schedule repeats, as an interval and unit joined by a pipe - "1|day", "2|week" or "1|month". Required when is_scheduled is true.

  - `destination_meta` (object)
    Where a scheduled report delivers its file. source selects the transport, sftp or ftp, and the remaining keys configure it: sftp takes sftp_host, sftp_port, sftp_username, sftp_authentication (password or key), then sftp_password or sftp_privateKey, and an optional sftp_directory; ftp takes ftp_host, ftp_port, ftp_username, ftp_password, ftp_passive and ftp_ssl. Keys that do not belong to the chosen source are stripped on save, the whole object is discarded if is_scheduled is false, and credentials are stored encrypted.

  - `meta` (object)
    Additional per-report-type options. use_field_value outputs the stored value of a custom field rather than its label. Some report types require their own subkeys - the inventory bundle type requires meta.bundle_template_id.

  - `report_category_id` (integer)
    Optional category to file the report under. Reports left uncategorised return null.

## Response 201 fields (application/json):

  - `object` (object)

  - `object.id` (integer)

  - `object.report_type_id` (integer)

  - `object.report_category_id` (string | null)

  - `object.user_id` (integer)

  - `object.name` (string)

  - `object.filters` (array)

  - `object.columns` (array)

  - `object.columns.name` (string)

  - `object.columns.label` (string)

  - `object.columns.value` (string)

  - `object.sorting` (array)

  - `object.grouping` (array)

  - `object.with_media` (integer)

  - `object.with_subaccounts` (integer)

  - `object.file_path` (string | null)

  - `object.file_type` (string)

  - `object.status` (string)

  - `object.error_message` (string | null)

  - `object.is_scheduled` (integer)

  - `object.start_date` (string | null)

  - `object.start_time` (string | null)

  - `object.end_date` (string | null)

  - `object.timezone` (string | null)

  - `object.repeat` (string | null)

  - `object.meta` (array)

  - `object.last_generated_at` (string | null)

  - `object.destination_meta` (string | null)

  - `object.deleted_at` (string | null)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `nice` (object)

  - `nice.rrn` (string)

  - `nice.status` (string)

  - `nice.columns_preview` (string)

  - `relations` (object)

  - `relations.report_type` (object)

  - `relations.report_type.object` (object)

  - `relations.report_type.object.id` (integer)

  - `relations.report_type.object.type` (string)

  - `relations.report_type.object.name` (string)

  - `relations.report_type.object.entities` (array)

  - `relations.report_type.object.only_trashed` (integer)

  - `relations.report_type.object.filters` (string | null)

  - `relations.report_type.object.deleted_at` (string | null)

  - `relations.report_type.object.created_at` (string)

  - `relations.report_type.object.updated_at` (string)

  - `relations.report_type.nice` (array)

  - `relations.report_type.permissions` (object)

  - `relations.report_type.permissions.read` (boolean)

  - `relations.report_type.permissions.update` (boolean)

  - `relations.report_type.permissions.delete` (boolean)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)

  - `permissions.share` (boolean)