Filtering by Tags in the Breeze API using filter_json

You may encounter difficulties when trying to filter people by specific tags using the filter_json parameter in the Breeze API. Initial attempts, such as using a JSON structure like {"tag_contains":"YOUR_TAG_ID"}, might result in an empty list [] or errors, even if you are certain the tag ID is correct and applied to records.

For example, an API call like this (using youraccount.breezechms.com as a placeholder for your specific Breeze domain) might not work as expected: https://youraccount.breezechms.com/api/people?filter_json={"tag_contains":"3864978"}

The solution involves a precise formatting of the tag ID within the JSON string and ensuring the entire JSON string is correctly URL encoded. The key adjustments include prefixing the tag ID and adhering to a specific JSON structure that includes a space after the colon before the value.

Detailed Steps & Explanation to Correct the API Call:

Let's say your original tag ID is 3864978 and your initial, non-working API call structure for the filter was: filter_json={"tag_contains":"3864978"}

Here’s how to modify it to the working version:

1. Identify the Correct Filter Key: The filter key within the JSON object remains tag_contains.
2. Format the Tag ID Value:
   • Prefix Requirement: The Breeze API, for this specific filtering method, requires the numerical tag ID to be prefixed with y_.
     • Original Tag ID: 3864978
     • Formatted Tag ID: y_3864978
3. Construct the Correct JSON String:
   • The JSON object should use the tag_contains key and the newly formatted tag ID as its value.
   • Crucially, based on working examples, include a space character after the colon (:) and before the opening quote (") of the tag ID value.
     • Correct JSON Structure: {"tag_contains": "y_3864978"} (Note the space)
4. URL Encode the JSON String: The entire JSON string constructed in step 3 must be URL encoded before it can be safely and correctly included as a query parameter in the API call URL.
   • Unencoded JSON: {"tag_contains": "y_3864978"}
   • URL Encoded Result: %7B%22tag_contains%22%3A%20%22y_3864978%22%7D
     • { becomes %7B
     • " becomes %22
     • : becomes %3A
     • (space) becomes %20
     • } becomes %7D
5. Assemble the Final API Call: Combine your base API URL, any other necessary parameters (like limit or details), and the correctly formatted and encoded filter_json parameter.

Example of the Corrected API Call:

If your Breeze account URL is https://youraccount.breezechms.com (replace youraccount with your actual Breeze subdomain) and you want to include limit=1 and details=1, using the example tag ID 3864978, the final, working API call would be:

https://youraccount.breezechms.com/api/people?limit=1&details=1&filter_json=%7B%22tag_contains%22%3A%20%22y_3864978%22%7D

Key Takeaways:

• Prefix is Crucial: For tag filtering with tag_contains in this manner, the y_ prefix on the numerical tag ID is essential.
• JSON Formatting Matters: The space after the colon in the JSON string ("tag_contains": "value") directly translates to %20 in the URL encoding and appears to be necessary for the filter to be correctly interpreted by the API.
• Always URL Encode: JSON strings used as values in URL query parameters must always be URL encoded. While tools like Postman might do this automatically if you input the raw JSON in the value field, understanding the encoded result is vital for troubleshooting or manual URL construction.

If you are still facing issues, double-check each step, ensure your tag ID is correct, and refer to any official Breeze API documentation or Facebook Users Group forums for help.