Query List Endpoints

Query Stax Bill list endpoints with pagination, filtering, sorting, and event suppression.

Supported controls

• Use pageSize and pageNumber to paginate list results.
• Use query for string matching, date/time ranges, and numeric ranges.
• Use sortOrder and sortExpression to sort list results.
• Use the X-SUPPRESS-ALL-EVENTS request header to suppress automated communications for bulk operations.

Pagination

For API requests that return a list, Stax Bill limits the maximum number of returned JSON entities. This maximum threshold varies by entity type but is never below 1,000. Use the query string parameters pageNumber and pageSize to paginate the results.

Examples

1. Read the first page.

   HTTP

   GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0

   This request returns the first 100 customers.

2. Read the next page.

   HTTP

   GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=1

   This request returns the next page of 100 customers.

Response headers for paginated requests

Stax Bill sends custom HTTPS response headers to make pagination easier to read programmatically.

Filter string fields

Use the query query string parameter for field value matching on endpoints that return lists.

• Separate the field name and value with :.
• Separate multiple filter-value pairs with ;.
• Matching is case-insensitive.
• Use wildcards * for partial matches.
• Use [empty] to check whether a string field is null or empty.

The available query parameter names are provided in the API reference for each endpoint.

Examples

Match one field

GET https://secure.fusebill.com/v1/customers?pageSize=1&pageNumber=0&query=firstName:Jessica

This call returns up to 1 customer entity with the firstName Jessica.

Match two fields

GET https://secure.fusebill.com/v1/customers?pageSize=1&pageNumber=0&query=firstName:Jessica;lastName:Smithson

This call returns up to 1 customer entity with the firstName Jessica and the lastName Smithson.

Match empty values

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=reference:[empty]

This call returns up to 100 customer entities with no value for reference.

Match partial values

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=primaryPhone:555*

This call returns up to 100 customer entities where primaryPhone starts with area code 555. If the query string were query=primaryPhone:*555*, phone numbers like 5556780987, 4555671234, and 2504741555 would all count as matches.

Match enum values

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=status:Active,Draft

The comma allows for multiple conditions. This call returns up to 100 customers with status equal to Active or Draft. Comma-separated values are supported only on enum type fields like status.

Match IDs in a set

GET https://secure.fusebill.com/v1/customers?query=id:123,456,789

The comma separates different values. This call returns customers with ID values in the set {123, 456, 789}. This can also be used with certain other Integer type fields like invoiceDay on the List Subscriptions endpoint.

Match special characters

GET https://secure.fusebill.com/v1/customers?pageSize=1&pageNumber=0&query=reference:am%26per%26sand

This call returns up to 1 customer entity with the value of reference equal to am&per&sand. Since the ampersand character is used to separate query strings, it must be URL-encoded. Similar issues occur with characters like commas, so use URL encoding for those characters as well.

Filter date/time and numeric fields

Use the query parameter for date/time and numeric range filtering on endpoints that return lists. All times shown and used in the Stax Bill API are UTC.

• Use the format field:lower|upper.
• Leave the lower bound empty for negative infinity.
• Leave the upper bound empty for positive infinity.
• Use YYYY-MM-DD for dates, or add time as YYYY-MM-DDTHH:MM:SS for more granularity.

If you provide a range like 2018-01-01|2019-01-01, Fusebill translates that to 2018-01-01T00:00:00|2019-01-01T00:00:00. That includes timestamps that occurred on 2018-01-01 but not 2019-01-01.

Examples

Closed interval

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=createdTimestamp:2018-01-01|2019-01-01

This call returns up to 100 customers who were created during 2018.

Lower-bounded interval

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=modifiedTimestamp:2018-01-01|

This call returns up to 100 customers with a last modified timestamp of January 1, 2018 or later.

Upper-bounded interval

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=createdTimestamp:|2019-01-01

This call returns up to 100 customers created before 2019-01-01.

Numeric range

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=monthlyRecurringRevenue:50.00|180.00

This call returns up to 100 customers with a monthly recurring revenue between 50.00 and 180.00. As with date ranges, that range could be |180.00 for values from negative infinity to 180.00, or 50.00| for values from 50.00 to infinity.

Combine ranges

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&query=monthlyRecurringRevenue:50.00|180.00;modifiedTimestamp:|2020-01-01

This call returns up to 100 customers who satisfy both conditions. They must have a monthly recurring revenue between 50.00 and 180.00, and their last modified timestamp must be before 2020-01-01. The semicolon (;) separates filter-value pairs and can also be used to combine range filtering and string filtering in the same API call.

Sorting

Use sortOrder and sortExpression to sort the array of JSON objects returned by a list request. Provide both query string parameters when you use a custom sort scheme.

• sortOrder can be Ascending or Descending.
• sortExpression is a query parameter name.
• Any query parameter name that can be used for string matching or date filtering can be used for sortExpression.

Examples

Sort by time

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&sortOrder=Descending&sortExpression=createdTimestamp

This call returns 100 customer entities ordered from the most recently created customer to the 100th most recently created customer.

Sort by string

GET https://secure.fusebill.com/v1/customers?pageSize=100&pageNumber=0&sortOrder=Ascending&sortExpression=firstName

This call returns 100 customer entities sorted by the lexicographical order of the firstName field. Lexicographical order for a string field goes from null to digits to letters. An ascending order of strings would be null, 123, 234, alpha, bravo, and so on.

You can verify what is being sorted by checking the custom response headers X-SortOrder and X-SortExpression.

Event suppression

Use the X-SUPPRESS-ALL-EVENTS request header when you do not want an API request to trigger automated communications for bulk operations, including Salesforce updates, emails, webhooks, and QuickBooks updates.

Example

POST https://secure.fusebill.com/v1/customers
X-SUPPRESS-ALL-EVENTS: True

With this header, the request will not trigger an automated webhook or email event.

Event suppression request header