Report Library API

The CertCentral Report Library API allows you to build reports that run automatically to get customized sets of data from your CertCentral account. Use the Report Library API to create reports for:

  • Certificate orders
  • Domains
  • Organizations
  • Audit logs
  • Balance history
  • FQDNs and wildcard usage

Authentication

The Report Library API uses header-based API keys for authentication and authorization. To authenticate to the Report Library API service, use your CertCentral API key. For step-by-step instructions on creating an API key, see Authentication.

In requests to the Report Library API, place your API key in the custom HTTP header X‑DC‑DEVKEY. For example, here's a sample request to the List report history endpoint:

bash
curl --request GET 'https://api.digicert.com/reports/v1/report/history' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json'

Only CertCentral admins can use the Report Library API. The API key in your requests must belong to a CertCentral user with the Administrator access role.

Base URL

Use this base URL when constructing Report Library API requests:

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

URL query strings

Some GET requests return a list of records that you can filter, sort, and paginate using URL query strings.

The syntax for query strings is {{name}}={{value}}. To apply multiple filters, append each query string to the request URL with an & character. For example, this request to the List report history endpoint uses two filters:

  • report_type=orders: Limits response to order reports.
  • schedule=MONTHLY: Limits response to reports that run on a monthly schedule.
generic
https://api.digicert.com/reports/v1/report/history?report_type=orders&schedule=MONTHLY

To create a filter that matches more than one value, provide a comma-separated list of each value that meets your filter criteria. For example, this request to the same List report history endpoint uses a filter that matches against multiple values:

  • report_display=test,example: Limits response to records with a display name of test or example.
generic
https://api.digicert.com/reports/v1/report/history?report_display_name=test,example

Requests

All requests you submit to the Report Library API use RESTful URLs and REST features, including header-based authentication and JSON/XML request types. The data character set encoding for requests is UTF-8. A well-formed request uses port 443 and has the user-agent and content-length headers specified.

Methods

  • GET
  • POST
  • PUT
  • DELETE

Body

Requests that require a payload accept JSON-formatted data. Include the header content-type: application/json in your request.

Responses

Responses consist of headers and a body. Response headers are based on the RFC 2616 specification. The body is formatted based on the content-type specified in the request.

Report formats

All report types except FQDN are formatted as a single data structure (CSV, JSON) or spreadsheet (EXCEL) containing data for each row and column in the report. Reports with many rows are split into multiple files for download (see Download report - Reports with multiple files).

FQDN reports are formatted as an Excel workbook containing two worksheets:

  • FQDN summary
  • FQDN details

The Report Library can only generate FQDN reports as Excel files. Additionally, large FQDN reports are not split into multiple files for download.

Report storage

To give you time to download your data, DigiCert stores the results of each report run for several months.

  • DigiCert stores the results of a report run for 90 days after the first time someone downloads the results.
  • If a report run completes and no one downloads the results for 6 months, DigiCert sends a reminder email to all users designated to receive report notifications. DigiCert automatically deletes the results 30 days after sending this email. If someone downloads the results before they are deleted, DigiCert stores the results for an additional 90 days.

Language support

By default, reports and API responses use English for column display names and report type descriptions. To translate these values into a language other than English, when you submit a request to an API that supports multiple languages, include the language_id query parameter in the request URL. Set the value of the language_id parameter to the ID of the language you want to use (see Glossary - Locale codes).

For example:

generic
https://api.digicert.com/reports/v1/report/types?language_id=2

These GET requests support the option to return column display names and report type descriptions in another language:

To generate reports that use a language other than English for column headings, include the language_id query parameter in your request to create or edit a report.

To create reports in the same language as the authenticated user's CertCentral profile, first submit a request to the User info API. Then, in the User info response, get the value of the language_id response parameter. Use this ID as the value of the language_id query string when you submit a request to create or edit a report.