Filters reference and examples

Use column filters to remove unwanted data from reports

Column filters allow you to build reports that only include the data you need. You can add, change, or remove filters when you create or edit a report.

Add a filter

To add a filter, include the filters array in your API request to create or edit a report. In your JSON payload, place the filters array inside the report_metadata object.

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. 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 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 Filter types.
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 and examples - Filter operators.

You can only add filters for columns included in the report. In other words, the column_identifier value for a filter must also be present in the report_metadata.columns array.

Filter operators

Filter operators define how we determine if the contents of a column meet the filter criteria. To get the filter operators that a column supports, use the List columns endpoint.

Name Include row if filtered column contains:
in Value that is an exact match for a value in the filter.
contains Value where any part of the value is an exact match a value in the filter.

For example, if the list of filter values includes the string digicert, any of these column values is a match: digicert, example_digicert, and digicert_example.
month_to_date Date between the beginning of the current calendar month and now.
quarter_to_date Date between the beginning of the current quarter and now.
year_to_date Date between the beginning of the current year and now.
last_30_days Date within the last 30 days.
last_12_months Date within the last 12 months.
custom_date Date within a custom date range. 

When using the custom_date operator, the list of values contains two elements that defines a date range. The first element is the start date and the second element is the end date. Use this format for dates: YYYY-MM-DD. For example: ["2021-01-01", "2021-01-31"]
last_month Date in the previous month.
expires_within_7_days Expiration date within the next 7 days.
expires_within_30_days Expiration date within the next 30 days.
expires_within_60_days Expiration date within the next 60 days.
expires_within_90_days Expiration date within the next 90 days.
expires_within_120_days Expiration date within the next 120 days.
expires_within_180_days Expiration date within the next 180 days.
expired_in_the_last_7_days Expiration date within the previous 7 days.
expired Expiration date in the past.

Filter types

A column's filter type describes the values the column can be filtered against.

  • Some columns allow filtering against a list of any custom values.
  • Some columns only allow filtering against a limited set of possible values.
  • Some columns provide filter operators that define the range of matching values. When using one of these operators, the filter criteria should not include a list of values to match against.

To get the filter type for each column in a report, use the List columns endpoint.

Name Description
multi_value The value of the column is compared to the values you provide when you create the filter.
  • If the List columns endpoint provides a list of possible values for a column:
    The filter criteria for the column is restricted to these values. If you try to add a filter that uses other values as the filter criteria, the API returns an error.
  • If the List columns endpoint does not provide a list of possible values for a column:
    There are no restrictions on the filter criteria for the column. You can filter against any values you choose.
static The operator defines the filter criteria for this column. When you create a filter, leave the values array blank.
date For columns with this filter type, most of the operators are a date range that defines the filter criteria for the column. When you create a filter, leave the values array blank.

The exception is when using the custom_date operator. For this operator, the list of values defines a custom range of dates. The first element is the start date and the second element is the end date. For example, see Filter by order_created_date below.
intermediate_ca_api The value of the column is compared to the list of intermediate ICA names in the filter. To get the names of intermediate ICAs in your account, use the List intermediates endpoint.
user_api The value of the column is compared to the list of user IDs in the filter. To get the ID value for users in your account, use the User list endpoint.
product_api The value of the column is compared to the list of product names in the filter. To get the names of products in your account, use the Product list endpoint.
organization_api The value of the column is compared to the list of organization IDs in the filter. To get the ID value for organizations in your account, use the Organization list endpoint.
dcv_method_api The value of the column is compared to the list of DCV method identifiers in the filter. To get a list of DCV method identifiers, use the List DCV methods endpoint.
validation_type_api The value of the column is compared to the list of validation types in the filter. To get a list of validation type identifiers, use the Validation types endpoint.

Example: Filter by status (multi_value)

Order reports include a status column. The filter type for this column is multi_value.

To customize an order report to only include orders with a pending status, add a filter with these attributes:

  • The column identifier is status.
  • The list of values contains a single value to match against: ["Pending"].
  • The operator (filter_identifier) required to find an exact match is in.

In the request payload to create or edit the report, the filters array looks like this:

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

Example: Filter by certificate_requested_date (date)

Order reports include an certificate_requested_date column. The filter type for this column is date.

To customize an order report to only include certificates requested between the beginning of the current month and now, add a filter with these attributes:

  • The column identifier is certificate_requested_date.
  • The operator (filter_identifier) required to find an certificate_requested_date between now and the beginning of the current month is month_to_date.
  • The list of values is empty. The month_to_date operator determines the date range for matching values.

In the request payload to create or edit the report, the filters array looks like this:

json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "month_to_date",
        "column_identifier": "certificate_requested_date",
        "values": []
      }
    ],
  …
  }
…
}

Alternatively, to customize an order report to only include orders created between January 1-7, 2021, add a filter with these attributes:

  • The column identifier is certificate_requested_date.
  • The operator (filter_identifier) required to find an order_created_date within a custom range is custom_date.
  • The list of values contains two elements that define a custom date range. The first element is the start date and the second element is the end date: ["2021-01-01", "2021-01-07"].

In the request payload to create or edit the report, the filters array looks like this:

json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "custom_date",
        "column_identifier": "certificate_requested_date",
        "values": [
          "2021-01-01",
          "2021-01-07"
        ]
      }
    ],
  …
  }
…
}

Example: Filter by days_remaining_until_expiration (static)

Order reports include a days_remaining_until_expiration column. The filter type for this column is static. Static filters do not use operators that match against a custom list of values. For static filters, the operator determines the range of acceptable values.

For example, to build an order report that only includes orders that expire within 30 days, add a filter with these attributes:

  • The column identifier is days_remaining_until_expiration.
  • The list of values is empty.
  • The operator (filter_identifier) required to find orders that expire within 30 days is expires_within_30 days.

In the request payload to create or edit the report, the filters array looks like this:

json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "expires_within_30_days",
        "column_identifier": "days_remaining_until_expiration",
        "values": []
      }
    ],
  …
  }
…
}

Example: Filter by product_name (product_api)

Order reports include a product_name column. The filter type for this column is product_api. This filter type tells us that we can use the Product list endpoint in the Services API to get the values we can use as filter criteria.

To build an order report that only includes orders for Basic OV certificates, first call the Product list endpoint to get the product name for the Basic OV product. Then add a filter with these attributes:

  • The column identifier is product_name.
  • The list of values contains identifiers for each product the report should include : ["Basic OV"].
  • The operator (filter_identifier) required to find an exact match is in.

In the request payload to create or edit the report, the filters array looks like this:

json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier": "in",
        "column_identifier": "product_name",
        "values": ["Basic OV"]
      }
    ],
  …
  }
…
}

Customize filter criteria using multiple filters

When creating or editing a report, you can add as many filters as you like. For columns that support the in or contains filter operator, you can even add multiple filters to the same column.

Adding multiple filters with the same column identifier creates an "or" condition. This means a row is included in the report if the value of the filtered column meets any of the filter criteria.

You can only create an "or" condition for columns that support the in or contains filter operators. Other filter operators require the value of the column to be a specific date or within a date range.

For example, this filters array creates a report that includes rows for any orders where the value of the common name (common_name) column:

  • Is an exact match for example.com OR
  • Is an exact match for example.net OR
  • Contains the string digicert OR
  • Contains the string security
json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters":[
      {
        "filter_identifier":"in",
        "column_identifier":"common_name",
        "values": [
          "example.com",
          "example.net"
         ]
       },
       {
         "filter_identifier":"contains",
         "column_identifier":"common_name",
         "values":[
           "digicert",
           "security"
          ]
       }
    ],
  …
  }
…
}

Adding multiple filters with different column identifiers creates an "and" condition. This means a row is only included in the report if the value in each filtered column meets all of the filter criteria.

For example, this filters array creates a report that includes rows for any orders where:

  • The value of the common name (common_name) column contains example AND
  • The value of the product name (product_name) column is Secure Site Pro SSL
json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters":[
      {
        "filter_identifier":"contains",
        "column_identifier":"common_name",
        "values": [
          "example.com"
         ]
       },
       {
         "filter_identifier":"in",
         "column_identifier":"product_name",
         "values":[
           "Secure Site Pro SSL"
         ]
       }
    ],
  …
  }
…
}

You can also create filter criteria that combines "and" conditions with "or" conditions.

For example, this filters array creates a report that includes rows for any orders where:

  • The order status (order_status) column is Revoked AND
  • The product name (product_name) column is Secure Site Pro SSL OR Secure Site Pro EV SSL AND
  • The order created date (order_created_date) column has a date between 2021-01-01 and 2021-01-07 AND
  • Any part of the string in the common name (common_name) column contains example.com OR example.net
json
{
…
  "report_metadata": {
    "report_type": "orders",
    "columns": […],
    "filters": [
      {
        "filter_identifier":"in",
        "column_identifier":"order_status",
        "values":[
          "Revoked"
        ]
      },
      {
        "filter_identifier":"in",
        "column_identifier":"product_name",
        "values":[
          "Secure Site Pro SSL",
          "Secure Site Pro EV SSL"
        ]
      },
      {
        "filter_identifier": "custom_date",
        "column_identifier": "order_created_date",
        "values": [
          "2021-01-01",
          "2021-01-07"
        ]
      },
      {
        "filter_identifier":"contains",
        "column_identifier":"common_name",
        "values":[
          "example.net",
          "example.com"
        ]
      }
    ],
  …
  }
…
}