Payload Filters

Payload filters restrict which records are visible through a given API key. When a payload filter is configured, the serialized JSONAPI response for each record is matched against the filter:

• List endpoints: Non-matching records are filtered out of the response.
• Single-resource endpoints: A 403 Forbidden status is returned if the record does not match the filter.

If the payload filter is empty or not set, the API key behaves normally and all records are returned.

Configuring a payload filter

You can configure a payload filter for an API key in the Dashboard. Navigate to API Keys, click into a specific key, and select the Payload filter tab. The filter is a JSON object that you can edit directly.

Examples

Filtering by status

To restrict an API key to only return completed Inquiries, you would set the following payload filter:

1
{
2
  "data": {
3
    "attributes": {
4
      "status": "completed"
5
    }
6
  }
7
}

When listing Inquiries with this filter, only those with "status": "completed" in their serialized payload will appear. Retrieving a single Inquiry that is not completed will return a 403.

Filtering by relationship

To restrict an API key to only return records associated with a specific Inquiry Template:

1
{
2
  "data": {
3
    "relationships": {
4
      "inquiry-template": {
5
        "data": {
6
          "id": "itmpl_abc123def456"
7
        }
8
      }
9
    }
10
  }
11
}

Designing a payload filter

Start by looking at the API response for the resource you want to filter. For example, retrieving an Inquiry (via Retrieve an Inquiry) might return:

1
{
2
  "data": {
3
    "type": "inquiry",
4
    "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
5
    "attributes": {
6
      "status": "completed",
7
      "reference-id": null,
8
      "...": "...",
9
      "tags": ["INBOUND", "CAMPAIGN ABC"],
10
      "fields": {
11
        "address-country-code": {
12
          "type": "string",
13
          "value": "US"
14
        },
15
        "...": "..."
16
      }
17
    },
18
    "relationships": {
19
      "inquiry-template": {
20
        "data": {
21
          "type": "inquiry-template",
22
          "id": "itmpl_abc123def456"
23
        }
24
      },
25
      "...": "..."
26
    }
27
  }
28
}

Pick the value you want to filter on and keep only the keys in the path leading to that value. For example, to filter for Inquiries with country code US:

1
{
2
  "data": {
3
    "attributes": {
4
      "fields": {
5
        "address-country-code": {
6
          "value": "US"
7
        }
8
      }
9
    }
10
  }
11
}

Matching against arrays

To match against an array value in the payload, provide an array in the filter containing the elements you want to check for. All elements in the filter array must be present in the payload array for the record to match.

Matching on Inquiries with a tag named “INBOUND”:

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": [
5
        "INBOUND"
6
      ]
7
    }
8
  }
9
}

Matching on Inquiries with both “INBOUND” and “CAMPAIGN ABC” tags:

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": [
5
        "INBOUND",
6
        "CAMPAIGN ABC"
7
      ]
8
    }
9
  }
10
}

$or operator

To allow for multiple criteria, use the $or operator. It can be used on a list of values or JSON object literals.

Value example — match Inquiries with either of two Inquiry Templates:

1
{
2
  "data": {
3
    "relationships": {
4
      "inquiry-template": {
5
        "data": {
6
          "id": {
7
            "$or": [
8
              "itmpl_abc123def456",
9
              "itmpl_ghi789jkl012"
10
            ]
11
          }
12
        }
13
      }
14
    }
15
  }
16
}

Object example — match Inquiries that are either approved or completed:

1
{
2
  "data": {
3
    "attributes": {
4
      "$or": [
5
        {
6
          "status": "approved"
7
        },
8
        {
9
          "status": "completed"
10
        }
11
      ]
12
    }
13
  }
14
}

$or on array fields

When using $or to match against a field whose value is an array (like tags), the $or must be placed at the parent level, not directly on the array field. Each option should wrap the array field with the value(s) to match.

This will not work — $or directly on an array field:

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": { "$or": ["US 1", "CAN 1"] }
5
    }
6
  }
7
}

Instead, place $or at the parent level with each option wrapping the array:

1
{
2
  "data": {
3
    "attributes": {
4
      "$or": [
5
        { "tags": ["US 1"] },
6
        { "tags": ["CAN 1"] }
7
      ]
8
    }
9
  }
10
}

This also composes with other filters using AND semantics. For example, to match (tag “US 1” OR tag “CAN 1”) AND (one of several templates):

1
{
2
  "data": {
3
    "attributes": {
4
      "$or": [
5
        { "tags": ["US 1"] },
6
        { "tags": ["CAN 1"] }
7
      ]
8
    },
9
    "relationships": {
10
      "inquiry-template": {
11
        "data": {
12
          "id": {
13
            "$or": ["itmpl_aaa", "itmpl_bbb", "itmpl_ccc"]
14
          }
15
        }
16
      }
17
    }
18
  }
19
}