Using the filters parameter in the Customer API

Tags: Flow

Most endpoints in the Customer API have a filters parameter that gives you the ability to make a single call to retrieve information that might otherwise require multiple calls.

Tip: Let’s say you’re interested in finding all aliases associated with two different users. By listing both those users in the filters parameter when you query the user_alias API endpoint, you can find all aliases in one call, instead of making two different calls.

Use the filters parameter to set AND and OR operators, represented by & and |, respectively, on different variables or values.

This parameter must be formatted and encoded in specific ways to accurately filter the API response.

  • Select which parameters from the endpoint you want to filter with.

  • Encode each key value pair you want to add to the parameter.

    • When using the parameter in the interactive API documentation, the key value pairs must be single-encoded.

    • When using a third party client or script to access the API, the key value pairs must be double-encoded.

  • Place the encoded key value pairs between unencoded AND or OR operators.

Important: Do not encode & or |. If encoded, the filter will not correctly apply.

If the encoding is not completed correctly, there are a couple possible outcomes:

  • The API may return an Unrecognized input error.

  • The filter may not make any change to the response.

If the response is not returning the expected values, confirm you’ve correctly encoded the parameter.

Using the example above of trying to find all aliases associated with either of two email addresses, a correctly encoded filters parameter, used in a script, should look something like:|

Notice that each key value pair is double-encoded, but the operator is not encoded.

back to top

If you need help, please contact Pluralsight Support.