API Response Filters

Feature overview

API response filters, also known as filters or API filters, simplify the response output and improve performance dramatically. Coupa Admins can create and manage API response filters to get expenses, requisitions, invoices, purchase orders, and user resources. You can designate a default filter for one or more of those resources to automatically apply that filter to all calls on that controller and you can define a filter to apply to multiple resource types. You can test the API filter from the same API Filter detail page used for configuration and it also keeps a history of changes made to the filter.

Filters can also be used with Remote Approver call outs and Tax Engine call outs. Call outs of those types allow you to specify a filter to simplify the message sent to those endpoints.

The newly added fields within the APIs will only appear in API responses when accompanied by a specific field mentioned in API response filters or the 'fields' query parameter.

What we were thinking

Coupa's default API responses can have more information than your third-party systems need. They can return many levels of associations that your service may not need.

Call outs can also send more information than is needed for a remote approver service or a tax service. Filters set on those call out types allow you to specify what resource fields get sent in the message body.

Your API response filters can reduce the output of the call response so it sends just what your service needs without the overhead required to handle more than what your external service needs. 

API response filters can be created for the following resources:

• Invoices
• Order headers
• Order lines
• Users
• Expense headers
• Expense lines
• Requisitions

The API Filter creation page allows quick iteration and it maintains a history of changes,so you can quickly test your filter, check the response, and modify it to get just what you need.

How it works

When Coupa API filters are used to constrain the volume of data needed for the response, less data sent means lower latency in response time. Simplifying the output to what is needed for system integration reduces both the initial human evaluation time and later the computing time for parsing and processing. 

Coupa Admins and systems integration users with the api_filters/index permission can see the API Response Filters interface at Setup > Integrations > API Filters.

The initially seeded filters are labeled using the pattern "default_[ResourceName]_filter" and are pre-set filters that represent best practices. These seeded filters are already trimmed down and do not include all available fields (attributes), but instead represent those fields most commonly needed for integration efforts. You can add or remove more resource fields to change the initially seeded set by creating your own filter or by editing the default resource filter.  

Default API Filter

When checked the Default checkbox applies the filter to all API calls to GET that resource. Each resource may have only one default API filter.

When the Default checkbox is cleared, that API filter may be used by adding a query string param: ?filter='[API Filter Name]' to the GET call for that resource.

Filter

The API Filter is positive, meaning listed attributes are shown in the response. Add or remove those resource attributes so the Filter passes the resource object attributes to your third-party system and Save prior to testing. 

The filter syntax also allows use with more than one document type. By default a new filter will contain attributes that correspond to the resource selected in the first step of creating the filter, but you can add filter text to apply to other document types. If a call out or web hook uses an API response filter for another document the filter specification for the other document is just ignored.

Here below is a screenshot example of filter syntax with two document types highlighted. Below the graphic you can click to expand the same filter with selectable text.

Click for an example of filter syntax for requisition lines and order line changes with selectable text.

[
  "id",
  "created_at",
  "updated_at",
  "need_by_date",
  "status",
  "submitted_at",
  "ship_to_attention",
  "line_count",
  "exported",
  "total",
  {
    "custom_fields": [
      "migrated_po_number",
      "last_integrated_successfully"
    ]
  },
  {
    "currency": [
      "code",
      "decimals"
    ]
  },
  {
    "requested_by": [
      "id",
      "login",
      "fullname",
      "email",
      "work_level"
    ]
  },
  {
    "ship_to_address": [
      "name",
      "location_code",
      "street1",
      "street2",
      "city",
      "state",
      "postal_code",
      "vat_number",
      "local_tax_number",
      "company_code"
    ]
  },
  {
    "requisition_lines": [
      "id",
      "description",
      "line_num",
      "need_by_date",
      "order_line_id",
      "quantity",
      "receipt_required",
      "source_part_num",
      "unspsc_code",
      "status",
      "total",
      "line_type",
      "unit_price",
      {
        "dci_category": [
          "name",
          {
            "lookup": [
              "name"
            ]
          }
        ]
      },
      {
        "account": [
          "name",
          "code",
          "segment_1",
          "segment_2",
          "segment_3",
          {
            "account_type": [
              "name"
            ]
          }
        ]
      },
      {
        "ul_contract": [
          "name",
          "description",
          "external_ref_num"
        ]
      },
      {
        "custom_fields": [
          "ext_line_num",
          "material_type",
        ]
      },
      {
        "commodity": [
          "name",
          "category",
          "subcategory"
        ]
      },
      {
        "account_allocations": [
          "amount",
          "pct",
          {
            "account": [
              "name",
              "code",
              "segment_1",
              "segment_2",
              "segment_3",
              {
                "account_type": [
                  "name"
                ]
              }
            ]
          }
        ]
      },
      {
        "attachments": [
          "id",
          "created_at",
          "updated_at",
          "type",
          "intent",
          "file",
          "file_file_name",
          "file_file_size"
        ]
      },
      {
        "currency": [
          "code"
        ]
      },
      {
        "supplier": [
          "name",
          "display_name",
          "number",
          "pcard_account",
          {
            "custom_fields": [
              "payment_term_list"
            ]
          }
        ]
      },
      {
        "uom": [
          "code"
        ]
      }
    ]
  },
  {
    "order_line_changes": [
      "id",
      "created_at",
      "updated_at",
      "line_num",
      "description",
      "need_by_date",
      "order_header_change_id",
      "order_line_id",
      "price",
      "quantity",
      "total",
      "paid_amount",
      {
        "custom_fields": {}
      }
    ]
  },
  {
    "current_approval": [
      "id",
      "approvable_type",
      "approvable_id",
      "delegate_id"
    ]
  },
  {
    "created_by": [
      "id",
      "login",
      "fullname",
      "email",
      "work_level"
    ]
  },
  {
    "updated_by": [
      "id",
      "login",
      "fullname",
      "email",
      "work_level"
    ]
  },
  {
    "preparer": [
      "id",
      "login",
      "fullname",
      "email",
      "work_level"
    ]
  }
]

Reset

You can Reset the filter to the initially seeded values if you want to restore it to its original list or you can expand the history of changes for reference.

Test

You can check the output response of your filter by first entering a known id value in the Test Filter on field and then clicking TEST.  All the standard role security applies to what you can see with the test, but your saved API Filter responds with the specified subset of parameter fields in an easy to read JSON format.

As an operator

The fields query operator allows you to pass the fields you want in the response body. The format of the fields value is JSON. Please refer to the example below:

?fields=["id","invoice_number",{"invoice_lines":["id","line_num"]}]

Availability

This feature is available for all Coupa customers.