How to build a report

The Report Library API allows you to build reports that run on a schedule to provide you with customized data from your CertCentral account.

When you build a report, you create a new report record. The report record describes the data to include in the report, how to organize and filter the data, and the schedule for running the report. To create a new report record, submit a POST request to the Create report endpoint:

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

Prepare your request

The Create report endpoint accepts a JSON payload with fields that define these report attributes:

Report type
Format (file type)
Report columns (data fields)
Schedule
Column filters
Data sources (subaccounts and divisions)
Notifications and emails

1. Choose report type

The report type determines what data the report will include. Each report type has unique configuration options and columns that you can filter in different ways. Report types include:

Report type	Identifier	Description
Order	`orders`	Details about certificate orders you have access to.
Domain	`domains`	Details about domains in your account, including validation details.
Balance history	`balance-history`	Account balance and transaction history.
Audit log	`audit-logs`	Data from audit log entries.
Organization	`organizations`	Details about organizations in your account, including validation details.
FQDN	`fqdn`	Details about FQDN and wildcard usage for active orders.
Users	`users`	Details about users for a given account.

To set the report type, use the report_type request parameter. In your Create report request, place the report_type parameter inside the report_metadata object. For example:

Example 1. orders

{
  "display_name": "Example order report",
  …
  "report_metadata": {
    "report_type": "orders",
    …
  }
  …
}

Example 2. audit-logs

{
  "display_name": "Example audit log report",
  …
  "report_metadata": {
    "report_type": "audit-logs",
    …
  }
  …
}

Example 3. domains

{
  "display_name": "Example domains report",
  …
  "report_metadata": {
    "report_type": "domains",
    …
  }
  …
}

Example 4. balance-history

{
  "display_name": "Example balance history report",
  …
  "report_metadata": {
    "report_type": "balance-history",
    …
  }
  …
}

Example 5. organizations

{
  "display_name": "Example organizations report",
  …
  "report_metadata": {
    "report_type": "organizations",
    …
  }
  …
}

2. Choose report format

The report format determines the file type of the report:

CSV
JSON
EXCEL

Note

Some formats are unavailable for certain report types. To see which formats a report type supports, check the value of the supported_formats fields in the List report types response.

To choose the format for a report, use the format array in your request. Because reports are only generated in one format, the format array should only contain one item. Place the format array at the top level of the request payload.

For example, this request creates a report that generates the results of a report run as a downloadable CSV file:

{
  "display_name": "Example report",
  "format": ["CSV"],
  …
}

3. Choose report columns

Columns determine what data the report will include. Each report type has different columns. To see the columns you can add to each report type, use the List columns endpoint.

To add columns to a report, use the columns array. The columns array is a list of objects containing the identifier of columns to include in the report. The order of objects in the array is the same as the column order in the generated reports. Place the columns parameter inside the report_metadata object in the request.

For example, this request creates an order report with columns for the account ID, number of SANs, certificate ID, and the validity period of the certificate in days:

{
  "display_name": "Example report",
  …
  "report_metadata": {
    "report_type": "orders",
    "columns": [
      {
        "identifier": "account_id"
      },
      {
        "identifier": "number_of_sans"
      },
      {
        "identifier": "certificate_id"
      },
      {
        "identifier": "certificate_validity_days"
      }
    ],
    …
  }
}

4. Schedule report

When you create a report, you can schedule it to run automatically or on-demand.

To define the report schedule, use the schedule object in your request. For detailed information about each field in the schedule object, see the reference documentation for the Create report endpoint. Place the schedule object at the top level of the JSON payload. For example:

Example 6. Last day of every month

{
  "display_name": "Example report",
  "schedule": {
    "frequency": "MONTHLY",
    "repeat_every": 1,
    "repeat_on": "DATE_OF_THE_MONTH",
    "repeat_on_date": {
      "last_day_of_the_month": true
    }
  },
  …
}

Example 7. Every 2 weeks on Tuesday

{
  "display_name": "Example report",
  "schedule": {
    "frequency": "WEEKLY",
    "repeat_every": 2,
    "weekday_to_run": "TUESDAY"
  },
  …
}

Example 8. Fifth day of every third month

{
  "display_name": "Example report",
  "schedule": {
    "frequency": "MONTHLY",
    "repeat_every": 3,
    "repeat_on": "DATE_OF_THE_MONTH",
    "repeat_on_date": {
      "date": 5,
      "last_day_of_the_month": false
    }
  },
  …
}

Example 9. Second Monday of every month

{
  "display_name": "Example report",
  "schedule": {
    "frequency": "MONTHLY",
    "repeat_every": 1,
    "repeat_on": "DAY_OF_THE_MONTH",
    "weekday_to_run": "MONDAY",
    "weekday_frequency": "SECOND"
  },
  …
}{
  "display_name": "Example report",
  "schedule": {
    "frequency": "WEEKLY",
    "repeat_every": 2,
    "weekday_to_run": "TUESDAY"
  },
  …
}

Example 10. On-demand

{
  "display_name": "Example report",
  "schedule": {
    "frequency": "ON_DEMAND",
  },
  …
}

5. (Optional) Add column filters

Column filters allow you to build reports that only include the data you need.

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.

To add a filter, include the filters array in your Create report request. The filters array is a list of objects. Each object defines a single filter. Filter objects include these key/value pairs:

Name	Type	Description
column_identifier	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	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	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.

Note

For more information and examples of how to use different filter types and operators, see Filters reference and examples.

When you submit a Create report request, place the filters array inside the report_metadata object. For example:

{
  …
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "in",
        "column_identifier": "status",
        "values": [
          "Pending"
        ]
      }
    ],
    …
  }
  …
}

6. (Optional) Choose sources

Some report types allow you include subaccounts and divisions as data sources for the report. If a report type supports this option, you can customize which subaccounts and divisions to use as sources by including the sources object in your JSON request.

Note

To see which report types support the option to customize subaccount and division sources, check the value of the sub_account_enabled and division_enabled fields in the List report types response.

The sources object includes these key/value pairs:

Name	Req/Opt	Type	Description
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	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	List of IDs for each subaccount to include in the report. Required if `sub_account_filter_type` is `CHOOSE_SUBACCOUNTS`.

Place the sources object inside the report_metadata object in your request payload. For example:

{
  "display_name": "Example report",
  …
  "report_metadata": {
    "sources": {
      "division_filter_type": "CHOOSE_DIVISIONS",
      "divisions": [123, 345, 456],
      "sub_account_filter_type": "CHOOSE_SUB_ACCOUNTS",
      "subaccounts": [123, 345, 456]
    },
    …
  }
  …
}

7. (Optional) Add notification emails

When you create a report, you can assign users to receive notification emails about the report. These notifications include:

Alerts when a new report is ready to download.
Warnings when a report you have not downloaded is about to be deleted.

The Report Library can only send notification emails to admins in your CertCentral account. To assign users to receive notification emails, include the notification_emails array in the body of your request. The notification_emails array is a list of objects containing details about the users who receive emails about the report. You can add as many users as you like.

Each object in the notification_emails array includes these key/value pairs:

Name	Req/Opt	Type	Description
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.

Place the notification_emails array at the top level of the request payload. For example:

{
  "display_name": "Example report",
  "notification_emails": [
    {
      "user_id": 1234567,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com"
    }
  ],
  …
}

Submit your request

When you're ready, submit your complete request to the Create report endpoint:

Example 11. 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"
    }
  }
}'

If you schedule the report to run on-demand, the report run starts the moment the report is created. Otherwise, the schedule in the report record determines the start date of the first report run.

What's next

After creating a report, you can:

Download completed report runs. Use the List report history endpoint to get the ID and status of each report run. If the status is READY, you can Download the report.
Suspend the report. To suspend a scheduled report without removing completed report runs, use the Delete scheduled report endpoint.
Edit the report. To change the schedule, format, columns, or any other report attributes, or to resume a suspended report, use the Edit report endpoint.
Delete the report. Ready to remove the data for a report and all of its runs from your account? Use the Delete report endpoint.

In this section: