Querying

Intro

Querying lets you refine the results of each request, where applicable, by specifying the attributes of records in the response payload. To achieve that, use the querying operator as the path 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 a property name that we need to filter
Operator is a logic operator or construction of logic operators
value is a sought value of the property.

Query format

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

The propertyName is endpoint-based and may vary from one endpoint to another (check FilterQuery parameter).

Using 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 will return an error message.

Date filtering

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

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

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

🚧
upSWOT filtering does not support DateTime with only year value such as "2020" as a parameter.

Querying operators

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

SYMBOL	EXPOSITION	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`	-

❗️
By default, all the filtering is applied to the first page, which size is 100 elements. To extend the filtering coverage, change the PageSize value to cover the entire sample.

Examples

All bank accounts for a specific category

Query: typeSystem = "Cash"

curl --request GET \
     --url https://sandbox.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 are not synced

Query: statusCode != 19

curl --request GET \
     --url https://sandbox.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 with cost more than $1000

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

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