Create report

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

Use this endpoint to create a report.

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:
  • weekday_to_run is MONDAY
  • weekday_frequency is FIRST
.. repeat_every conditional string Number of weeks or months between each report run.
Range:
  • If frequency is WEEKLY: 1-2
  • If frequency is MONTHLY: 1-3
For example, to run a report every two weeks:
  • freqeuncy is WEEKLY
  • repeat_every is 2
.. repeat_on conditional string For monthly reports, whether to initiate report runs on a specific day or date.
Possible values:
  • DAY_OF_THE_MONTH - Initiate report runs on a specific day (for example, on the first Monday of the month.
  • DATE_OF_THE_MONTH - Initiate report runs on a specific date (for example, on the 10th day of the month) .
.. .. 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). See supported_formats 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.

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. You can only add filters for columns included in the report.
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.
.. .. values conditional array of strings List of values. For each item in the report, the value of the column is compared to the values in this list. Reports only include an item if the column for that item 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 and examples - Filter types.
.. .. 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 and examples - Filter 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": "INCLUDE_ALL_DIVISIONS"
  • "sub_account_filter_type": "EXCLUDE_ALL_SUB_ACCOUNTS"
.. .. 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.

Response parameters

Name Type Description
report_identifier string Report ID (UUID).
message string Report creation message.

About

DigiCert is the world's leading provider of scalable TLS/SSL, IoT and PKI solutions for identity and encryption. The most innovative companies, including 89% of the Fortune 500 and 97 of the 100 top global banks, choose DigiCert for its expertise in identity and encryption for web servers and Internet of Things devices. DigiCert supports TLS and other digital certificates for PKI deployments at any scale through its certificate lifecycle management solution, CertCentral®. The company is recognized for its enterprise-grade certificate management platform, fast and knowledgeable customer support, and market-leading security solutions. For the latest DigiCert news and updates, visit digicert.com or follow @digicert.

©2020 DigiCert, Inc. All rights reserved. DigiCert, its logo and CertCentral are registered trademarks of DigiCert, Inc. Norton and the Checkmark Logo are trademarks of NortonLifeLock Inc. used under license. Other names may be trademarks of their respective owners.