Search
Introduction
Searchable fulfillmenttools entities have their own search endpoint, located at: POST /api/{ENTITY-NAME}/search
. Every fulfillmenttools entity defines which fields are queryable in its search endpoint.
Strings and numbers can be searched with the operators
eq
andnotEq
(search value needs to be a string) orin
andnotIn
(search value needs to be an array of strings)
Arrays of strings can be searched with the
contains
operatorNumbers and date values can be searched with the operators
gt
(>),gte
(>=),lt
(<) andlte
(<=)customAttributes
are fully searchable. However, to optimize performance, we recommend storing search-relevant keys in a dedicated property (e.g., searchTerms) and minimizing nesting depth.
Fields with Default Query Limits
Some entities (particularly those representing historical data) include default filters in queries. These default search fields are designed to limit the amount of data returned, improving performance and relevance.
For example, operational entities such as orders typically return only recently created records by default, as older data is often not relevant for current operations.
These default values can be overwritten if needed. However, we recommend caution when expanding filters, especially when querying large datasets, to avoid performance issues.
Search function limitations
The search functionality has restrictions due to database constraints and performance considerations. These limitations ensure stability and efficiency when handling queries.
No dots (
.
) in custom search field names: Field names containing dots (.
) can cause conflicts with internal database structures and indexing mechanisms. To prevent issues, dots are not allowed in custom search field names.No custom search fields starting with a dollar sign (
$
): Field names beginning with a dollar sign ($
) conflict with database operators, which use this syntax for system commands. To avoid ambiguity, such field names are not permitted.Cross-entity search via
referenced
filter is limited to top-level queries: Cross-entity searches using thereferenced
filter can only be applied at the top level. Nesting them withinAND
orOR
conditions is not supported due to query optimization constraints.
Example API calls
Searching for exact equal matches
Example: Search for stocks in a facility with facilityRef
d083f631-9f4c-463b-85d4-9414fb19239f
.
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/stocks/search
{
"query": {
"facilityRef": {
"eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
}
}
}
Searching with gt
, gte
, lt
and lte
operators
gt
, gte
, lt
and lte
operatorsExample: Search for storage locations created before the 2nd October 2024.
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/storagelocations/search
{
"query": {
"created": {
"lt": "2024-10-02T14:43:21.257Z"
}
}
}
Sorting search results
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
"sort": [
{
"<attribute_to_sort_by>": "ASC"
}
],
"query": {
...
}
}
Adding a search result total count
The total count can significantly slow down the response time of the request.
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
"options": {
"withTotal": true
},
"query": {
...
}
}
Searching for several fields in conjunction with and
/or
and
/or
Example: Search for stocks in facility with facilityRef
d083f631-9f4c-463b-85d4-9414fb19239f
and that are placed on locations 6779689d-4852-4fcf-b13b-78f5ce4954d8
and 3b8be595-6a00-40cf-be09-12195e44eb99.
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/stocks/search
{
"query": {
"and": [
{
"facilityRef": {
"eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
}
}, {
"locationRef": {
"in": [
"6779689d-4852-4fcf-b13b-78f5ce4954d8",
"3b8be595-6a00-40cf-be09-12195e44eb99"
]
}
}
]
}
}
Searching for nested fields
Example: Search for inboundProcesses
with a purchaseOrder
with ID 678ujnuzb67vg8h8oji
.
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/inboundprocesses/search
{
"query": {
"purchaseOrder": {
"id": {
"eq": "678ujnuzb67vg8h8oji"
}
}
}
}
Searching for custom attributes
Fields in customAttributes
can be made searchable by defining key-value pairs within the searchTerms
property. All defined key-value pairs are then queryable in the search endpoints. The customAttributes
can contain strings and numbers. For strings, the in
and notIn
operators are allowed. For numbers, the operatorslt
, lte
, gt
, gte
are additionally available.
It is important to use numbers when searching for a number attribute and strings when searching for a string attribute. Otherwise, the search will not give back the desired results. For example, if the search value is the number 5
, a query search for eq: "5"
would not be successful.
Example: Create a new storage location with user-defined custom attributes that should be searchable and execute the search.
Create a new entity with user-defined custom attributes that should be searchable (
searchTerms
)
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/{facilityId}/storagelocations
...
"customAttributes": {
"searchTerms": {
"TYPE": "FROZEN"
}
}
...
Construct a search query on custom attributes
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/storagelocations/search
{
"query": {
"customAttributes": {
"searchTerms": {
"TYPE": {
"eq": "FROZEN"
}
}
}
}
}
Last updated