Add a filter

  5 minute read  

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:

NameTypeDescription
column_identifierstringColumn to filter by.
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.
Note: In most cases, you can only add filters for columns included in the report. In other words, to add a filter, the column_identifier value for the filter must also be present in the report_metadata.columns 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 report_metadata.columns array. To see if a column can only be used as a filter, check the value of the filter_only parameter in the List columns API response.
valuesarray of stringsList 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 Filters reference: Types and operators.
filter_identifierstringOperator 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: Types and operators.

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:

{
…
  "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:

{
…
  "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:

{
…
  "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:

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