Updates to ‘query’ API to properly handle invalid criteria and values
The following release information is for developers using the “query” API functionality:
The launch of the new Audience Builder allowed for additional validation to be used within the the tool. This validation prevents audience searches from being run on illogical criteria, such as dates that aren’t actually dates, or characters that aren’t numbers. We are extending this validation to the “query” API, to prevent developers from running jobs that ultimately fail because of bad criteria.
Beginning Sept. 20, 2017, the following “query” API uses will return an API error, instead of the ultimate result of failure to complete. In all cases below, the jobs would ultimately fail for not matching proper criteria and values. These only affect uses of the query API, as Audience Builder’s interface automatically protects against the below scenarios.
The “engagement_min” and “engagement_max” criteria previously treated out-of-bounds (too high / too low) numbers differently than other invalid values, such as random letters. We are updating the search so that invalid criteria will match zero users.
The criteria “carnival_devices_not” is being removed in favor of “NOT(Carnival Devices)”.
Invalid date values combined with the “not_since_date” and “not_since_days” criteria time ranges previously matched no one. Beginning Sept. 20, 2017, these criteria will be converted to “NOT(since_date)” and “NOT(since_days)”, which will begin matching everyone.
The /job API previously did not reject malformed queries (e.g. missing parenthesis or invalid relative date values.) The API will now reject these queries, instead of waiting for a job to run that ultimately fails.
Marketers should make note of these updates with their development teams, but note that action is not likely needed. We have reached out to customers that used these queries in the past 90 days to make them aware of the upcoming changes, and to help correct their queries to identify their proper audience.
If you have any questions, please contact your Customer Success team member, or email firstname.lastname@example.org