Querying

Querying lets you refine the results of each request, where applicable, by specifying the attributes of records in the response payload. To do this, use the querying operator as a query parameter. This way, you get only relevant data based on your specific request.

How to Refine the Response with Querying

The query has the following structure: {propertyName}{Operator}{value}, where:

propertyName is the property to filter on
Operator is a logic operator or combination of logic operators
value is the value you're filtering for

Query Format

🚧
To perform querying, use URL-encoded characters for the HTTP requests. See the reference.

propertyName depends on the endpoint you're calling and varies from one endpoint to another — check that endpoint's FilterQuery parameter for its supported properties.

Use ampersands (&&) for AND queries, or pipes (||) for OR queries, to separate multiple query clauses.

🚧
The total length of your query should not exceed 2048 characters. If your query is longer, the API returns an error message.

Date Filtering

To filter responses based on a DateTime field, use the following format: YYYY-MM-DDTHH:MM:SS.ssssss (example: 2024-03-20T09:53:41.209835).

If only the date is defined, the default time 12:00:00 AM is used for filtering.

📘
All dates in the API are returned in UTC using ISO-8601 (e.g. 2020-01-02T15:04:05Z).

🚧
Business Health filtering does not support DateTime with only a year value, such as 2020, as a parameter.

Querying Operators

The following table shows comparison operators supported for numeric, date, and string data types.

SYMBOL	MEANING	URL Encoded	IMPLICATION
=	Equals	`%3d`	Numbers, Strings, Date, Boolean, GUID
!=	Not Equals	`%21%3d`	Numbers, Strings, Date, Boolean, GUID
~	Contains	`%7E`	Strings
>	Greater than	`%3e`	Numbers, Date
<	Less than	`%3c`	Numbers, Date
>=	Greater than or equal to	`%3e%3d`	Numbers, Date
<=	Less than or equal to	`%3c%3d`	Numbers, Date
&&	AND	`%26%26`	-
\|\|	OR	`%7C%7C`	-

Examples

All Bank Accounts for a Specific Category

Query: typeSystem = "Cash"

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/:companyId/banking/accounts?FilterQuery=typeSystem%3dCash \
     --header 'accept: application/json'\
     --header 'authorization: Bearer eyJhbGc.....'

All Company Data Connections That Aren't Synced

Query: statusCode != 19

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/company/:companyId/data-connection/statuses?FilterQuery=statusCode%21%3d19 \
     --header 'accept: application/json'\
     --header 'authorization: Bearer eyJhbGc.....'

All eCommerce Products That Cost More Than $1000

Query: baseCurrency = "USD" && cost >= 1000

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/:companyId/ecommerce/products?FilterQuery=baseCurrency%3dUSD%26%26cost%3e%3d1000 \
     --header 'accept: application/json'\
     --header 'authorization: Bearer eyJhbGc.....'

All Transactions Before a Specific Date

Query: date <= 2024-03-20

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/:companyId/accountancy/transactions?FilterQuery=date%3c%3d2024-03-20 \
     --header 'accept: application/json'\
     --header 'authorization: Bearer eyJhbGc.....'