API Filters - NovaGL/coupa-resources GitHub Wiki

For the next installment in my how-to series, we’re going to investigate API Filters. Think of API Filters as a super-charged fields view. Coupa is so confident in API Filters that it is going to replace the return_object parameter in a future release. The benefit of API Filters is that it allows you to return exactly what you want. Not only that but it allows you to drill-down into objects. You can also click the default button on an API filter to make that the default results when the API is called

Catalog items Example

A common request from my organization is that they want a full view of an items from a particular supplier, but an item is made up of various components.

• The supplier item.
• The parent item that the supplier item belongs to.
• The supplier
• Contract
• Contract Terms
• Catalog

Each of these sections have a separate endpoint which previously made it hard to get the data all together. However with API filters we can chain all these together in one API call to get the data

Name	catalog_supplier_items
Description	Supplier items view with catalog
Resource	supplier_items
Endpoint	/api/supplier_items/

Filter

[
  "id",
  "price",
  "price_tier_1",
  "price_tier_2",
  "price_tier_3",
  "price_tier_4",
  "supplier_part_num",
  "unspsc_code",
  "preferred",
  {
    "currency": [
      "code"
    ]
  },
  {
    "catalog": [
      "name"
    ]
  },
  {
    "supplier": [
      "name",
      "number"
    ]
  },
  {
    "item": [
      "id",
      "active",
      "name",
      "description",
      "image_url",
      "manufacturer_name",
      "manufacturer_part_number",
      {
        "uom": [
          "code"
        ]
      },
      {
        "commodity": [
          "name"
        ]
      },
      {
        "custom_fields": {}
      }
    ]
  },
  {
    "contract": [
      "number"
    ]
  },
  {
    "contract_term": [
      "name",
      "tier_1_upper_bound",
      "tier_2_upper_bound",
      "tier_3_upper_bound",
      "tier_4_upper_bound"
    ]
  },
  {
    "custom_fields": {}
  }
]

From the above you can see that it gets the price breaks from the supplier item but then tells you what tiers that refers to on the contract and it also tells you if the item is in a catalog.

Invoice Approvals Example

Lets say you have a simple request from your organization where they want to see a list of invoices pending approval, whose approved it and where its at.

Using the below filter you can set the API response to remove any information that is not required and show the approval information. This information will show you which approval positions have been approved and if not what stage they are at. It will also show you that approver. You could also drill-down further if you chose to see the members of an approval group

Name	invoice_approvals
Description	Invoice Approvals view
Resource	invoices
Endpoint	/api/invoices/

Filter

[
  "id",
  "created_at",
  "updated_at",
  "invoice_date",
  "invoice_number",
  {
    "supplier": [
      "name",
      "number"
    ]
  },
  {
    "invoice_lines": [
      "description",
      "line_num",
      "po_number",
      "price",
      "quantity",
      "total",
      "source_part_num"
    ]
  },
  {
    "approvals": [
      "position",
      "status",
      "approval_date",
      {
        "approved_by": [
          "login"
        ]
      },
      {
        "approver": [
          "name"
        ]
      },
      {
        "delegates": [
          "position",
          "status",
          "approval_date",
          "note"
        ]
      }
    ]
  },
  {
    "requested_by": [
      "login"
    ]
  }
]

Forms Example

API Filters also work with forms including your custom forms or SIM forms.

You can simplify the filter to show you only the current approver and the answers to all your form questions

Name	custom_responses
Description	Shows form responses
Resource	easy_form_responses
Endpoint	/api/easy_form_responses/

[
  "id",
  "name",
  "status",
  "submitted_at",
  "updated_at",
  {
    "requested_by": [
      "email",
      "fullname"
    ]
  },
  {
    "current_approval": [
      "position",
      "status",
      {
        "approver": [
          "name"
        ]
      }
    ]
  },
  {
    "subject": [
      {
        "custom_fields": {}
      }
    ]
  },
  {
    "easy_form_widget_responses": [
      "widget_label",
      "answer"
    ]
  }
]

The possibilities are endless, so next time you are busy trying to manipulate the results of an API call consider filtering on the server end.