---
title: "Add a filter"
source_url: https://dev.digicert.com/certcentral-apis/report-library-api/column-filters/add-a-filter.html
---

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:

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>column_identifier</td>
<td>string</td>
<td>Column to filter by.<br><strong>Allowed values:</strong> Varies by report type. To get the list of columns you can use as filters for a given report type, use the <a href="https://dev.digicert.com/md/certcentral-apis/report-library-api/list-columns.md">List columns</a> endpoint.<br><strong>Note:</strong> In most cases, you can only add filters for columns included in the report. In other words, to add a filter, the <code>column_identifier</code> value for the filter must also be present in the <code>report_metadata.columns</code> 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 <code>report_metadata.columns</code> array. To see if a column can only be used as a filter, check the value of the <code>filter_only</code> parameter in the <a href="https://dev.digicert.com/md/certcentral-apis/report-library-api/list-columns.md">List columns</a> API response.</td>
</tr>
<tr>
<td>values</td>
<td>array of strings</td>
<td>List of values. For each row in the report, the value of the filtered column (<code>column_identifier</code>) 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.<br>Not used if the <code>filter_type</code> for the column is static. For more information, see <a href="https://dev.digicert.com/md/certcentral-apis/report-library-api/column-filters/filters-reference-types-and-operators.md">Filters reference: Types and operators</a>.</td>
</tr>
<tr>
<td>filter_identifier</td>
<td>string</td>
<td>Operator that defines how to determine if the value in a column meets the filter criteria.<br><strong>Allowed values:</strong> Varies by column. To get the list of filter operators available for a given report type, use the <a href="https://dev.digicert.com/md/certcentral-apis/report-library-api/list-columns.md">List columns</a> endpoint. To learn more about filter operators, see <a href="https://dev.digicert.com/md/certcentral-apis/report-library-api/column-filters/filters-reference-types-and-operators.md">Filters reference: Types and operators</a>.</td>
</tr>
</tbody>
</table>

## Examples

### 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"
        ]
      }
    ],
  …
  }
…
}
```

### Filter by order_created_date (date)

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

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

- The column identifier is `order_created_date`.
- The operator (`filter_identifier`) required to find an `order_created_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": "order_created_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 `order_created_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": "order_created_date",
        "values": [
          "2021-01-01",
          "2021-01-07"
        ]
      }
    ],
  …
  }
…
}
```

### 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": []
      }
    ],
  …
  }
…
}
```

### 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](https://dev.digicert.com/md/certcentral-apis/services-api/products/product-list.md) 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:

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