Custom Attributes

The IF API allows you to define custom attributes for API resources. These attributes are key-value pairs that enable you to attach additional information to a resource based on your specific needs.

Custom attributes can also be used as filter parameters in "List" APIs, making it easier to refine and manage your data queries.

Refer to the table below for a list of resources that support this feature.

Custom attributes can also be used to pass service provider specific parameters from your system to IF. To ensure compatibility, please refer to each resource's documentation for a list of reserved attribute keys.

Custom Attributes Payload Structure

Use the following example as a standard template for handling custom attributes in the request and response payloads of create/update API operations:

{
  "workflow": {},
  "data": {
    "<resource>": {
      "<resourceField01>": "",
      "<resourceField02>": "",
      "attributes": {
        "<key-01>": "<value-01>",
        "<key-02>": "<value-02>",
      }
    }
  },
  "connect": {},
  "metadata": {}
}

The attributes field is also included in the responses for Get and List APIs, maintaining the same structure.

Filtering by Custom Attributes in List APIs

APIs that support custom attributes also enable filtering in their List APIs using these attributes. This is done by passing a dynamic query parameter in the request.

Query parameter template:

/<resource-path>?data.attributes[<key>]=<value>

Example use case:

If a card has a custom attribute called externalId with a value of 123456, you can filter the List Cards API to access this card as follows:

/cards?data.attributes[externalId]=123456