API documentationIncident ManagementFeedback
Edit

Search

Introduction

For more information about the Search API, see the API documentation for the respective search endpoint (e.g., for an inbound process: REST API documentation - Inbound Process).

Searchable fulfillmenttools entities have a dedicated search endpoint located at POST /api/{ENTITY-NAME}/search. Each fulfillmenttools entity defines which of its fields are queryable.

  • Users can search string and number fields with the operators eq, notEq, in, and notIn. The search value for eq and notEq must be a string, while the value for in and notIn must be an array of strings.

  • Users can search array-of-string fields with the contains operator.

  • Users can search number and date fields with the operators gt (>), gte (>=), lt (<), and lte (<=).

  • All customAttributes are searchable. However, to optimize performance, it is recommended to store search-relevant keys in a dedicated property (e.g., searchTerms) and minimize nesting depth.

Fields with default query limits

Some entities, particularly those representing historical data, include default filters in queries. These default search fields limit the amount of data returned, which improves 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 overridden if needed. However, expanding filters requires caution, especially when querying large datasets, to avoid performance issues.

Search function limitations

The search functionality has the following restrictions due to database constraints and performance considerations. These limitations ensure stability and efficiency when handling queries.

  1. 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.

  2. 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.

  3. Cross-entity search via referenced filter is limited to top-level queries: Cross-entity searches using the referenced filter can only be applied at the top level of a query. Nesting them within AND or OR conditions is not supported due to query optimization constraints.

Search execution time limit

Each search request must complete within a 30-second time limit. If execution exceeds this limit, the system aborts the search and returns a BadRequest response. Long runtimes can result from a combination of query complexity and the volume of entities searched. When encountering timeouts, reduce the complexity (e.g., simplify nested conditions, narrow filters, avoid overly broad customAttribute queries), narrow the size of the dataset (e.g., by providing a time range or restricting the search to a specific facility), or contact the support team for guidance.

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}.api.fulfillmenttools.com/api/stocks/search
{
    "query": {
        "facilityRef": {
            "eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
        }
    }
}

Searching with gt, gte, lt, and lte operators

Example: Search for storage locations with a created date before October 2, 2024.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/storagelocations/search
{
    "query": {
        "created": {
            "lt": "2024-10-02T14:43:21.257Z"
        }
    }
}

Sorting search results

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
    "sort": [
        {
            "<attribute_to_sort_by>": "ASC"
        }
    ],
    "query": {
      ...
    }
}

Adding a search result total count

Requesting the total count can significantly increase the response time of the request.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/{ENTITY-NAME}/search
{
    "options": {
        "withTotal": true
    },
    "query": {
      ...
    }
}

The withTotal option cannot be used in combination with after for pagination. This restriction exists because the total count may change while paginating, which could lead to inconsistent results.

Searching for several fields with and or or

Example: Search for stocks that have a facilityRef of d083f631-9f4c-463b-85d4-9414fb19239f and are also placed on either location 6779689d-4852-4fcf-b13b-78f5ce4954d8 or 3b8be595-6a00-40cf-be09-12195e44eb99.

POST https://{YOUR-TENANT-NAME}.api.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 that reference a purchaseOrder with the id 678ujnuzb67vg8h8oji.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/inboundprocesses/search
{
    "query": {
        "purchaseOrder": {
            "id": {
                "eq": "678ujnuzb67vg8h8oji"
            }
        }
    }
}

Searching for custom attributes

Users can make fields in customAttributes 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 lt, lte, gt, and gte operators are also available.

When searching a number attribute, use a number value in the query. Similarly, use a string value for a string attribute. Otherwise, the search will not return the expected results. For example, a search for the number 5 using eq: "5" will not be successful.

Example: Create a new storage location with user-defined, searchable custom attributes and then execute a search for them.

  1. Create a new entity with user-defined custom attributes that should be searchable via searchTerms.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/{facilityId}/storagelocations
...
"customAttributes": {
  "searchTerms": {
    "TYPE": "FROZEN"
  }
}
...

  1. Construct a search query on the custom attributes.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/storagelocations/search
{
  "query": {
    "customAttributes": {
      "searchTerms": {
        "TYPE": {
          "eq": "FROZEN"
        }
      }
    }
  }
}

Last updated