Searching using query language
Search using query language offers a unified and extensible mechanism for querying a resource. In GET list endpoints, it is exposed through the ?ql= parameter and enables clients to define structured queries based on the fields returned in the resource representation. Consumers can compose expressions to filter, combine, and refine results across any supported fields in a consistent way.
By comparison, search with classic query parameters relies on predefined filters (e.g., ?name=Ana&status=active) and typically supports only simple field-level matching. Query language–based search is better suited for advanced use cases, as it allows more complex conditions, logical operators, and scalable query construction within a single, standardized interface.
The query language is case-sensitive. For example, you cannot use [EQ] for “equal”; it must be written as [eq].
Separator
Parentheses () are used to group blocks of conditions within a query.
Logical operators
AND operator
AND operator is used to return records that match all combined conditions.
Example: Return documents where folder is PURCHASES and metadata.issueDate is 2026-01-15.
?ql=folder=PURCHASES AND metadata.issueDate=2026-01-15
OR operator
OR operator is used to return records that match any of the conditions.
Example: Return documents where folder is PURCHASES or metadata.issueDate is 2026-01-15.
?ql=folder=PURCHASES OR metadata.issueDate=2026-01-15
Operation operators
The operation operator is specified in square brackets before the field path, e.g.: metadata.documentTotals.vatAmount[eq]=1200.23.
Default operator
If no operator is specified, the standard equals sign = is applied by default and behaves the same as the [eq] operator.
Example: The two queries below will return the same result sets.
?ql=metadata.documentTotals.vatAmount=1200.23
?ql=metadata.documentTotals.vatAmount[eq]=1200.23
Number operators
For numeric values, the operator does not require the value to be enclosed in double quotes, e.g.: metadata.documentTotals.vatAmount[eq]=1200.23.
eq operator
The [eq] operator returns records that match the specified value exactly.
Example: Return documents where metadata.documentTotals.vatAmount equals 1200.23.
?ql=metadata.documentTotals.vatAmount[eq]=1200.23
ne operator
The [ne] operator returns records that do not match the specified value.
Example: Return documents where metadata.documentTotals.vatAmount doesn't equal 1200.23.
?ql=metadata.documentTotals.vatAmount[ne]=1200.23
gt operator
The [gt] operator returns records with values greater than the specified value.
Example: Return documents where metadata.documentTotals.vatAmount is greater than 1200.23.
?ql=metadata.documentTotals.vatAmount[gt]=1200.23
gte operator
The [gte] operator returns records with values greater than or equal to the specified value.
Example: Return documents where metadata.documentTotals.vatAmount is greater than or equal to 1200.23.
?ql=metadata.documentTotals.vatAmount[gte]=1200.23
lt operator
The [lt] operator is used to retrieve records where the value is less than the specified value.
Example: Return documents where metadata.documentTotals.vatAmount is less than 1200.23.
?ql=metadata.documentTotals.vatAmount[lt]=1200.23
lte operator
The [lte] operator returns records with values less than or equal to the specified value.
Example: Return documents where metadata.documentTotals.vatAmount is less than or equal to 1200.23.
?ql=metadata.documentTotals.vatAmount[lte]=1200.23
String operators
In the initial implementation phase, strings with accents are treated as different from strings without accents. For example, “La Férmé” is different from “La Ferme”. Therefore, when searching for “La Ferme”, the record of “La Férmé” will not match.
{
"legalName": "La Férmé"
}
Match:
?ql=legalName[eq]="La Férmé"
No match:
?ql=legalName[eq]="La Ferme"
The string operator must accept any of these cases:
- enclosed value in double quotes “ ”, e.g. metadata.documentNumber[cont]=”ABC”
- enclosed value in single quote ‘ ‘, e.g. metadata.documentNumber[cont]=’ABC’
- value not enclosed, e.g. metadata.documentNumber[cont]=ABC
eq operator
The [eq] operator returns records that exactly match the specified string value, with case sensitivity.
Example: Return documents where metadata.documentNumber equals exactly "ABCD_001", case-sensitive. Thus, "ABCD_001" will match, "abcd_001" will not match.
?ql=metadata.documentNumber[eq]="ABCD_001"
ieq operator
The [ieq] operator returns records that match the specified string value, ignoring case sensitivity.
Example: Return documents where metadata.documentNumber equals "ABCD_001", case-insensitive. Thus, "ABCD_001", "abcd_001", "Abcd_001", etc. will all match.
?ql=metadata.documentNumber[ieq]="ABCD_001"
cont operator
The [cont] operator returns records that contain the specified string value, with case sensitivity.
Example: Return documents where metadata.documentNumber contains "BCD", case-sensitive. Thus, "abcd_001" will not match.
?ql=metadata.documentNumber[cont]="BCD"
icont operator
The [icont] operator returns records that contain the specified string value, ignoring case.
Examplr: Return documents where metadata.documentNumber contains "BCD", case-insensitive. Thus, "ABCD_001", "abcd_001", "Abcd_001", etc. will all match.
?ql=metadata.documentNumber[icont]="BCD"
start operator
The [start] operator returns records where the field value begins with the specified string, with case sensitivity.
Example: Return documents where metadata.documentNumber starts by "ABC", case-sensitive. Thus, "abcd_001" will not match.
?ql=metadata.documentNumber[start]="ABC"
istart operator
The [istart] operator returns records where the field value begins with the specified string, ignoring case.
Example: Return documents where metadata.documentNumber starts with "ABC", case-insensitive. Thus, "ABCD_001", "abcd_001", "Abcd_001", etc. will all match.
?ql=metadata.documentNumber[istart]="ABC"
Other operators
in operator
The [in] operator is a shorthand for multiple OR conditions. It returns records that match any value in the specified list and is case-sensitive. Values must be enclosed in parentheses ().
Note: [in] applies to single-value fields. For array fields, use [any].
Example: Return documents where category is INVOICE or RECEIPT or QUOTE.
?ql=category[in]=("INVOICE","RECEIPT","QUOTE")
not_in operator
The [not_in] operator returns records that do not match any of the values in the list and is case-sensitive. Values must be enclosed in parentheses ().
Note: [not_in] applies to single-value fields.
Example: Return documents where category is not INVOICE and not RECEIPT and not QUOTE.
?ql=category[not_in]=("INVOICE","RECEIPT","QUOTE")
exists operator
The [exists] operator returns records based on whether the target field is present or missing.
Example: Return documents where metadata.documentTotals.netAmount is present, regardless of its value.
?ql=metadata.documentTotals.netAmount[exists]=true
Example: Return documents where metadata.documentTotals.netAmount is NOT present, regardless of its value.
?ql=metadata.documentTotals.netAmount[exists]=false
[
{
"id": "4e37d7a0-e844-4b45-8579-f60d73781be9",
"metadata": {
"documentTotals": {
"vatAmount": "15",
"netAmount": "100"
}
}
},
{
"id": "42868c9a-a1d1-4f41-86a5-d0f67d838101",
"metadata": {
"documentTotals": {
"vatAmount": "10"
}
}
}
]
any operator
The [any] operator returns records where an array field contains at least one of the specified values and is case-insensitive. Values must be enclosed in parentheses ().
Note: [any] applies only to array fields.
Example: Return documents where any of the tag values is "new".
?ql=tags[any]=("new")
Example: Return documents where any of the tag values is "new" or "seen".
?ql=tags[any]=("new","seen")
[
{
"id": "4e37d7a0-e844-4b45-8579-f60d73781be9",
"tags": ["new"]
},
{
"id": "42868c9a-a1d1-4f41-86a5-d0f67d838101",
"tags": ["new", "seen"]
}
]
Field path
Work with object
Fields inside an object can be accessed using dot notation.
Nested fields are supported at any depth, allowing queries on any level of the object hierarchy.
Example: Search top level field in the document.
?ql=category="INVOICE"
Example: Search second level field in the document.
?ql=metadata.documentNumber="ACBD001"
Example: Search third level field in the document.
?ql=metadata.documentTotals.grossAmount=1200.23
Field names containing special characters (e.g. space, dot, comma, quote, backslash, forward slash, etc.) must be enclosed in double quotes or single quote.
Example: Normal field name.
?ql=metadata.documentNumber=ACBD001
Example: Field name contains special characters (e.g. dots) must be enclosed around double quotes or single quote.
?ql=processingData.spaceExtensions."com.unifiedpost.btx.connectors".peppol.sbdhInstanceIdentifiers[any]=(12345_118e3040-51d2-11e3-6f96-0800200c9a66,92345_118e3040-51d3-11e3-8f96-0800200c9a66)
OR
?ql=processingData.spaceExtensions.'com.unifiedpost.btx.connectors'.peppol.sbdhInstanceIdentifiers[any]=(12345_118e3040-51d2-11e3-6f96-0800200c9a66,92345_118e3040-51d3-11e3-8f96-0800200c9a66)
{
"processingData": {
"spaceExtensions": {
"com.unifiedpost.btx.connectors": {
"peppol": {
"sbdhInstanceIdentifiers": [
"12345_118e3040-51d2-11e3-8f96-0800200c9a66"
]
}
}
}
}
}
Work with array
- Array of string:
Example: Return documents where any of the tag values is "new".
?ql=tags[any]=("new")
Example: Return documents where any of the tag values is "new" or "seen".
?ql=tags[any]=("new","seen")
[
{
"id": "4e37d7a0-e844-4b45-8579-f60d73781be9",
"tags": ["new"]
},
{
"id": "42868c9a-a1d1-4f41-86a5-d0f67d838101",
"tags": ["new", "seen"]
}
]
- Array of object:
Fields inside an array of objects can be accessed using the @ notation. The @ symbol refers to the fields of a single object within the array.
?ql=myArray[](@field1=value1 AND @field2=value2)
This query returns results where myArray contains at least one object with both field1 = value1 and field2 = value2.
Example: Return documents where any object inside the list of metadata.paymentMeans has code equals to 42.
?ql=metadata.paymentMeans[](@.code=42)
Example: Return documents where any object inside the list of metadata.paymentMeans has code equals to 42 or 33, and paymentAccount.identifier is "FR157841Z25".
?ql=metadata.paymentMeans[](@.code[in]=(42,33) AND @.paymentAccount.identifier="FR157841Z25")
[
{
"id": "4e37d7a0-l844-4b45-8579-f60d73781be9",
"metadata": {
"paymentMeans": [
{
"code": "42",
"text": "Payment to bank account, Belgian structured reference",
"paymentReference": {
"value": "001/4037/32870",
"type": "STRUCTURED",
"scheme": "OGM_VCS"
},
"paymentAccount": {
"identifier": "FR3330002005500000157841Z25",
"scheme": "IBAN",
"country": "FR",
"currency": "EUR",
"bank": {
"identifier": "ABCDEFG",
"scheme": "BIC"
}
},
"paymentLink": "https://tx.pay-nxt.com/payment-items/807594ae-...-166eca6e81a7"
}
]
}
}
]
Data types
Use the appropriate value format based on the data type of the field.
String & Enum
Values can be enclosed in double quotes, single quotes, or left unquoted, e.g.: metadata.documentNumber[eq]=ABC or metadata.documentNumber[eq]="ABC".
Example: Return documents where documentNumber equals ABCD_001.
?ql=metadata.documentNumber[eq]="ABCD_001"
OR
?ql=metadata.documentNumber[eq]=ABCD_001
Example: Return documents where category is INVOICE.
?ql=category="INVOICE"
Number
Do not enclose the value in double quotes, e.g.: metadata.documentTotals.vatAmount[eq]=1200.23.
Example: Return documents where metadata.documentTotals.vatAmount equals 1200.23.
?ql=metadata.documentTotals.vatAmount[eq]=1200.23
Date
Use the date format YYYY-MM-DD and do not enclose the value in double quotes, e.g.: metadata.issueDate[eq]=2026-01-15.
Example: Return documents where metadata.issueDate is 2026-01-15.
?ql=metadata.issueDate[eq]=2026-01-15
Datetime
Use the ISO 8601 datetime format YYYY-MM-DDTHH:mm:ssZ and do not enclose the value in double quotes, e.g.: createdAt[gt]=2026-10-04T14:20:31Z.
Example: Return documents where metadata.issueDate is greater than 2026-10-04T14:20:31Z.
?ql=createdAt[gt]=2026-10-04T14:20:31Z
Boolean
Do not enclose the value in double quotes, e.g.: metadata.vatAlreadyDeclared[eq]=true.
Example: Return documents where metadata.vatAlreadyDeclared is true.
?ql=metadata.vatAlreadyDeclared[eq]=true