Querying
Filtering
Endpoints for listing data types typically support filtering. The filter syntax is common for all endpoints and consists of a filter query parameter with the following syntax:
filter=<propName>:<op>:<value>
op
eq: equalsne: not equalsgt: greater thanlt: less thancontains: case-insensitive contains for array type propertiesin: in array, array elements separated with | (see example below)nin: not in array, array elements separated with | (see example below)
Example: …/document_types?filter=category:eq:Invoice
Contains vs in
The contains operator is typically used for array type properties, consider a deliveryMethod property which can hold multiple values, e.g. ['sms', 'email']. To filter for objects with sms delivery method one would use filter=deliveryMethod:contains:sms
The in operator is an OR operation, allowing to filter for objects with multiple values. Consider two objects with different values on an age property, e.g. a.age=5, b.age=7. To filter for both these one would use filter=age:in:5|7
Sorting
Sorting of lists is supported via sort and sortOrder query parameters:
sort=<propName>&sortOrder=order
Order: asc or desc for getting the list in ascending or descending order. Ascending is the default order.
Searching
Searching is supported via the search query parameter:
search=<search string>
Unlike filtering and sorting search is not performed on a specific property name, rather the search is carried out on all the searchable properties for the given data type. For example, a search on participants for the term 'acm' will return a participant with name=Acme as well as a participant with participantIdentifier=000x:123-acm-990.
The searchable properties for each datatype are listed in the table below.
Filter/sort support per endpoint
| Endpoint | Sort Properties | Filter Properties |
|---|---|---|
| /orgs/:id/transactions | createdAt, transactionStatus | createdAt, transactionStatus |
| /orgs/:id/participants | name, createdAt | createdAt, environment, apRef |
| /orgs/:id/users | name, createdAt, email | country, createdAt |
| /orgs/:id/webhooks/events | createdAt | eventType, createdAt, isEnabled |
| /orgs/:id | legalName, createdAt, participantCount | organisationMode, createdAt, country |
Search support per endpoint
| Endpoint | Search Properties |
|---|---|
| /orgs/:id/transactions | senderId, receiverId, senderSP, receiverSP, id, docInstanceId |
| /orgs/:id/participants | name, participantIdentifier |
| /orgs/:id/users | name, email |
| /orgs/:id/webhooks/events | payload |
| /orgs/:id | legalName, shortName, legalIdentifier |
Below is a concise summary of how to use filtering, sorting, and searching with the described endpoints.
| Concept | Syntax / Options | Notes / Examples |
|---|---|---|
| Filter syntax | filter=<propName>:<op>:<value> | Example: /document_types?filter=category:eq:Invoice |
| Filter operators | eq, ne, gt, lt, contains, in, nin | eq=equals, ne=not equals, gt=greater than, lt=less than, contains=array contains, in=in list, nin=not in list |
| contains vs in | contains: array contains value; in: OR over multiple values | contains example: docTypeName:contains:Invoice; in example: age:in:5|7 |
| Sorting syntax | sort=<propName>&sortOrder=<asc|desc> | Ascending is default if sortOrder is omitted |
| Search syntax | search=<search string> | Runs across all searchable properties for that endpoint, not a single field |
| /orgs/:id/transactions – sort | createdAt, transactionStatus | Example: ?sort=createdAt&sortOrder=desc |
| /orgs/:id/transactions – filter | createdAt, transactionStatus | Example: ?filter=transactionStatus:eq:COMPLETED |
| /orgs/:id/participants – sort | name, createdAt | Example: ?sort=name&sortOrder=asc |
| /orgs/:id/participants – filter | createdAt, environment, apRef | Example: ?filter=environment:eq:prod |
| /orgs/:id/users – sort | name, createdAt, email | Example: ?sort=email |
| /orgs/:id/users – filter | country, createdAt | Example: ?filter=country:eq:SE |
| /orgs/:id/webhooks/events – sort | createdAt | Example: ?sort=createdAt&sortOrder=desc |
| /orgs/:id/webhooks/events – filter | eventType, createdAt, isEnabled | Example: ?filter=isEnabled:eq:true |
| /orgs/:id – sort | legalName, createdAt, participantCount | Example: ?sort=participantCount&sortOrder=desc |
| /orgs/:id – filter | organisationMode, createdAt, country | Example: ?filter=organisationMode:eq:production |
| Searchable fields – /orgs/:id/transactions | senderId, receiverId, senderSP, receiverSP, id, docInstanceId | Example: ?search=acme-tx-123 |
| Searchable fields – /orgs/:id/participants | name, participantIdentifier | Example: ?search=acm |
| Searchable fields – /orgs/:id/users | name, email | Example: ?search=jane.doe |
| Searchable fields – /orgs/:id/webhooks/events | payload | Example: ?search=InvoiceCreated |
| Searchable fields – /orgs/:id | legalName, shortName, legalIdentifier | Example: ?search=Acme |
GET /orgs/123/transactions?filter=transactionStatus:eq:COMPLETED&sort=createdAt&sortOrder=desc&search=INV-2024-001
GET /orgs/123/participants?filter=environment:eq:prod&sort=name&search=acm
GET /orgs/123/users?filter=country:in:SE|NO&sort=createdAt&sortOrder=asc&search=john
GET /orgs/123/webhooks/events?filter=isEnabled:eq:true&sort=createdAt&sortOrder=desc&search=InvoiceCreated
GET /orgs/123?filter=country:eq:SE&sort=participantCount&sortOrder=desc&search=Acme