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.
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 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. |
A column's filter type describes the values the column can be filtered 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.
|
| 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. |
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:
status.["Pending"].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": "status",
"values": [
"Pending"
]
}
],
…
}
…
}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:
certificate_requested_date.filter_identifier) required to find an certificate_requested_date between now and the beginning of the current month is month_to_date.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:
{
…
"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:
certificate_requested_date.filter_identifier) required to find an order_created_date within a custom range is custom_date.["2021-01-01", "2021-01-07"].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": "custom_date",
"column_identifier": "certificate_requested_date",
"values": [
"2021-01-01",
"2021-01-07"
]
}
],
…
}
…
}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:
days_remaining_until_expiration.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:
{
…
"report_metadata": {
"report_type": "orders",
"columns": […],
"filters": [
{
"filter_identifier": "expires_within_30_days",
"column_identifier": "days_remaining_until_expiration",
"values": []
}
],
…
}
…
}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:
product_name.["Basic OV"].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"]
}
],
…
}
…
}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:
example.com ORexample.net ORdigicert ORsecurity{
…
"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:
common_name) column contains example ANDproduct_name) column is Secure Site Pro SSL{
…
"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:
order_status) column is Revoked ANDproduct_name) column is Secure Site Pro SSL OR Secure Site Pro EV SSL ANDorder_created_date) column has a date between 2021-01-01 and 2021-01-07 ANDcommon_name) column contains example.com OR example.net{
…
"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"
]
}
],
…
}
…
}