Edit report

PUT
https://api.digicert.com/reports/v1/report/{{report_identifier}}

Use this endpoint to edit a report.

When editing a report, keep these points in mind:

  • Changes you make only apply to future report runs.
  • If you change the frequency of a report schedule to ON_DEMAND, the report run starts the moment you submit a successful Edit report request.

The JSON payload in an Edit report request overwrites the existing report record.

In addition to new and updated fields, make sure your request includes any fields you want to keep the same. For example, when editing a report to add columns, the columns array should include the new column identifiers along with any column identifiers already added to the report. To get current values for fields in an existing report record, use the Report details endpoint.

Example requests and responses

cURL 
curl --request PUT 'https://api.digicert.com/reports/v1/report/{{report_identifier}}' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "display_name": "Example",
  "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_created_date"
      },
      {
        "identifier": "account_id"
      },
      {
        "identifier": "number_of_sans"
      },
      {
        "identifier": "certificate_id"
      },
      {
        "identifier": "certificate_validity_in_days"
      },
      {
        "identifier": "division_or_container_id"
      },
      {
        "identifier": "common_name"
      },
      {
        "identifier": "organization_name"
      },
      {
        "identifier": "order_status"
      }
    ],
    "filters": [
      {
        "filter_identifier": "in",
        "column_identifier": "common_name",
        "values": [
          "example.com"
        ]
      },
      {
        "filter_identifier": "in",
        "column_identifier": "organization_name",
        "values": [
          "Example Organization"
        ]
      },
      {
        "filter_identifier": "in",
        "column_identifier": "order_status",
        "values": [
          "Issued",
          "Pending"
        ]
      }
    ]
  }
}'
204 No Content 
// No content

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)

Path parameters

Name Req/Opt Type Description
report_identifier required string Report ID (UUID). To get the report ID, copy the report_identifier returned when you Create a report. Otherwise, use the Get report history endpoint.

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-31
.. .. 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 date 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 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 List of objects with information about users to notify when a report is generated and ready for download. User details must belong to an admin 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.
.. 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 List of objects that define the filters to add to the report.
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 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 value in the filtered column 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 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.

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.