String Filtering

Stax Bill can filter the results based on criteria for API requests that return a list. This is done through a specific query string parameter called query, which can be used for field value matching.



A: Simple matching on one field


This call returns up to 1 customer entity with the firstName “Jessica”. The colon character separates the query parameter name from the value being matched against. The available query parameter names are often the same as the field names in the response JSON. These query parameter names are provided in this API reference for the relevant calls.


B: Simple matching on two fields


This call returns up to 1 customer entity with the firstName “Jessica” and the lastName “Smithson”. The semicolon separates the filter-value pairs


C: Special value matching (null)


This call returns up to 100 customer entities with no value for reference. This is useful if there is a need to ensure no customers are without a custom value for reference. “[empty]” is a special string used to check if a string field is null or empty, since “null” would be interpreted as a string.


D: Partial matching


This call returns up to 100 customer entities such that the value of their primaryPhone field starts with area code 555. The asterisk simply means to accept 0 to infinity additional characters, and more than one asterisk can be used. If the query string were query=primaryPhone:*555* then phone numbers like “5556780987”, “4555671234”, and “2504741555” would all count as matches.


E: Set matching on enum fields


The comma allows for multiple conditions. This call will return up to 100 customers with status equal to “Active” or “Draft”. Comma separating values is supported only on enum type fields like status


F: Set matching on IDs


The comma separates different values. This call will return customers with ID values in the set {123, 456, 789}. This can be used with certain other Integer type fields like invoiceDay on the (v1/subscriptions/getAll)[] endpoint


G: special character matching


This call returns up to 1 customer entities with the value of reference equal to "am&per&sand". Since the ampersand character is used to separate query strings, its inclusion in the URL would be problematic. Similar problems would occur if a comma character were used. To solve this issue, the URL encoding for these characters must be used explicitly.