Create report

6 minute read

POST https://api.digicert.com/reports/v1/report

Use this endpoint to create a report.

Note

When creating a report, use date range filters to customize the time frame you want the report to cover. Otherwise, DigiCert creates the report using the default date range for the given report type. For more information, see Custom date ranges.

Example requests and responses

cURL

curl --request POST 'https://api.digicert.com/reports/v1/report' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "display_name": "Example report",
  "schedule": {
    "frequency": "MONTHLY",
    "weekday_to_run": "",
    "weekday_frequency": "",
    "run_until": "",
    "repeat_every": 3,
    "repeat_on": "DATE_OF_THE_MONTH",
    "repeat_on_date": {
      "date": 5,
      "last_day_of_the_month": false
    }
  },
  "format": [
    "CSV"
  ],
  "notification_emails": [
    {
      "user_id": 1234567,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com"
    }
  ],
  "report_metadata": {
    "report_type": "orders",
    "columns": [
      {
        "identifier": "order_id"
      },
      {
        "identifier": "order_status"
      },
      {
        "identifier": "serial_number"
      },
      {
        "identifier": "account_id"
      },
      {
        "identifier": "request_state"
      },
      {
        "identifier": "product_name"
      },
      {
        "identifier": "order_created_date"
      },
      {
        "identifier": "additional_email"
      },
      {
        "identifier": "user_or_requester_name"
      },
      {
        "identifier": "user_or_requester_email"
      },
      {
        "identifier": "common_name"
      },
      {
        "identifier": "sans"
      },
      {
        "identifier": "certificate_status"
      },
      {
        "identifier": "validity_start_date"
      },
      {
        "identifier": "validity_end_date"
      },
      {
        "identifier": "organization_name"
      }
    ],
    "filters": [
      {
        "filter_identifier": "custom_date",
        "column_identifier": "order_created_date",
        "values": [
          "2021-08-01",
          "2021-08-20"
        ]
      }
    ],
    "sources": {
      "division_filter_type": "INCLUDE_ALL_DIVISIONS",
      "sub_account_filter_type": "EXCLUDE_ALL_SUB_ACCOUNTS"
    }
  }
}'

201 Created

{
  "report_identifier": "e62b02f3-97f9-4fa1-9314-f9ecfdcaf5d7",
  "message": "Successfully created Custom Report"
}

URL query parameters

Name	Req/Opt	Type	Description
language_id	optional	int	ID of the language to use for column headings in generated reports.
Allowed values: See Glossary - Locale codes
Default: English (1)

Request parameters

Name	Req/Opt	Type	Description
display_name	required	string	Report display name. Allowed characters: a-z, A-Z, 0-9, and _:()[]
schedule	required	object	Object with key/value pairs that define the report schedule.
.. frequency	required	string	Frequency of report creation. Possible values: `ON_DEMAND`, `WEEKLY`, and `MONTHLY` (case-insensitive).
.. weekday_to_run	conditional	string	Day of the week to initiate a report run. Possible values: `SUNDAY` to `SATURDAY` (case-insensitive). Not required if `frequency` is `ON_DEMAND` or if `repeat_on` is `DATE_OF_THE_MONTH`.
.. weekday_frequency	conditional	string	Week of the month to initiate a report run. Possible values: `FIRST`, `SECOND`, `THIRD`, `FOURTH`, `LAST` (case-insensitive). For example, to run a report on the first Monday of every month:
.. repeat_every	conditional	string	Number of weeks or months between each report run. Range: For example, to run a report every two weeks:
.. repeat_on	conditional	string	For monthly reports, whether to initiate report runs on a specific day or date. Possible values:
.. .. repeat_on_date	conditional	object	Object with key/value pairs defining a monthly date when the report run initiates. Required if `repeat_on` is `DATE_OF_THE_MONTH`.
.. .. date	optional	integer	Day of the month on which a new report run is initiated. Range: 1-28
.. .. last_day_of_the_month	optional	boolean	If true, a new report run is initiated on the last day of the month. Otherwise, false.
.. run_until	optional	string	Date to stop generating reports. If undefined, the scheduler will continue to initiate report runs until you disable the report. Format: `YYYY-MM-DD`
format	required	array of strings	File format for generated reports. Because reports are only generated in one format, the formats array should only contain one item. Possible values: `CSV`, `JSON`, `EXCEL` (case-insensitive). The formats that each type of report supports are listed in the `supported_formats` array in the List report types response.
notification_emails	optional	array of objects	List of objects with information about users to notify when a report is generated and ready for download. Users must be admins in your CertCentral account.
.. user_id	required	integer	User ID.
.. first_name	required	string	User first name.
.. last_name	required	string	User last name.
.. email	required	string	User email address.
report_metadata	required	object	Object that defines the report type and data to include in the report.
.. report_type	required	string	Report type. Allowed values: See List report types.
.. columns	conditional	object	List of objects that define the columns to include in the report. The order of columns in this array matches the order of columns in the generated report. Note: FQDN (`fqdn`) report types do not allow column customization. When creating an `fqdn` report, omit the `columns` array from your request. For all other report types, `columns` is a required parameter, and must include identifiers for all required columns in the given report type.
.. .. identifier	required	string	Column identifier. Allowed values: See List columns. Column identifiers vary by report type.
.. filters	optional	array of objects	List of objects that define the report’s filters. To learn more about column filters, see Column filters.
.. .. column_identifier	required	string	Column to filter by.
Allowed values: Varies by report type. To get the list of columns you can use as filters for a given report type, use the List columns endpoint.
Note: In most cases, you can only add filters for columns included in the report. In other words, to add a filter, the column_identifier value for the filter must also be present in the report_metadata.columns array. However, some columns can only be used as filters. For these columns, you can add a filter, but you cannot include the column’s identifier in the report_metadata.columns array. To see if a column can only be used as a filter, check the value of the filter_only parameter in the List columns API response.
.. .. values	conditional	array of strings	List of values. For each row in the report, the value of the filtered column (column_identifier) is compared to the values in this list. A row is only included in the report if the filtered column contains a value that meets the filter criteria.
Not used if the filter_type for the column is static. For more information, see Filters reference: Types and operators.
.. .. filter_identifier	required	string	Operator that defines how to determine if the value in a column meets the filter criteria.
Allowed values: Varies by column. To get the list of filter operators available for a given report type, use the List columns endpoint. To learn more about filter operators, see Filters reference: Types and operators.
.. sources	optional	object	Object with key/value pairs that determine the sources of data for the report. If the report type can use subaccounts and divisions as sources, and if the sources object is empty or not provided, these defaults are applied:
.. .. division_filter_type	optional	string	Defines divisions to include in the report.
Possible values:
INCLUDE_ALL_DIVISIONS (default) - Report includes data from all divisions in your account.
INCLUDE_TOP_DIVISION - Report only includes data from the top-level division in your account.
CHOOSE_DIVISIONS - Report includes data from divisions you add to the divisions array.
EXCLUDE_ALL_DIVISIONS - Report only includes data from subaccounts. All parent account data is omitted. Note: Reports configured to omit parent account data must include subaccount data. In other words, when the value of division_filter_type is EXCLUDE_ALL_DIVISIONS, the value of sub_account_filter_type cannot be EXCLUDE_ALL_SUB_ACCOUNTS.
.. .. divisions	conditional	array of integers	List of IDs for each division to include in the report.
Required if division_filter_type is CHOOSE_DIVISIONS.
.. .. sub_account_filter_type	optional	string	Defines subaccounts to include in the report.
Possible values:
INCLUDE_ALL_SUB_ACCOUNTS - Report includes data from all subaccounts you manage.
EXCLUDE_ALL_SUB_ACCOUNTS (default) - Report does not includes subaccount data.
CHOOSE_SUB_ACCOUNTS - Report includes data from subaccounts you add to the sub_accounts array.
.. .. sub_accounts	conditional	array of integers	List of IDs for each subaccount to include in the report.
Required if sub_account_filter_type is CHOOSE_SUBACCOUNTS.