Search Documents

This guide covers all supported filters for querying documents in the Stonal platform. It details every filter you can use to refine your search queries.

---

Prerequisites

• A valid OAuth access token (see Authentication)
• Your organization code (used in the endpoint path)

---

1. Filter Groups & Fields

Each group represents a set of filters targeting different aspects of your documents.

1.1 Filing Location Filters

Filter	Type	Description
assetIdentifiers	Set[String]	Only return documents attached to these asset UIDs.
documentationIdentifiers	Set[String]	Only return documents linked to these documentation UIDs.
folderIdentifiers	Set[String]	Only return documents stored in these folder UIDs.

1.2 Business Context Filters

Filter	Type	Description
linkedAssetIdentifiers	Set[String]	Documents related to specific linked assets (e.g., building, apartments).
tenantIdentifiers	Set[String]	Documents belonging to or created by specific tenants.
linkedAsset	String	Partial or full name match of the linked asset—useful when you don’t have the UIDs on hand.

1.3 Basic Document Filters

Filter	Type	Description
identifier	Set[String]	Exact document UIDs to retrieve.
name	String	Partial or full name match (case-insensitive).
documentStatus	String	One of CLASSIFICATION, METADATA_EXTRACTION, COMPLETED.
hashSha256	String	SHA-256 checksum of the document’s contents.
updatedAfter	String	ISO-8601 timestamp to filter documents updated during or after this date.

1.4 Metadata Filters

Filter	Type	Description
tags	Set[String]	Documents tagged with one or more specified tags.
properties	Map[String,String]	Documents with matching metadata key-value pairs.
propertyKey	String	Documents containing a specific metadata key (regardless of value).

1.5 Folder & Classification Filters

Filter	Type	Description
parentFolderName	String	Partial match on the parent folder’s name.
predictedFolderName	String	AI-predicted folder name after classification.
folder	{ name, locale }	Match folder by exact name and locale.
documentClass	{ name, locale }	Match classification class by name and locale.

---

2. Search Document API Call

Send your query in one JSON payload:

curl -X POST "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/documents/search" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "tags": ["important","finance"],
    "folderIdentifiers": ["folder-123"],
    "assetIdentifiers": ["asset-456"],
    "linkedAsset": "Unit A",
    "pageNumber": 0,
    "pageSize": 100,
    "sortOrder": "DESC",
    "columnToSort": "creationDate",
  }'

---

3. Response Format

200 OK with JSON:

{
  "result": [],
  "total": 42,
  "pageable": {
    "pageNumber": 0,
    "pageSize": 100,
    "sort": {}
  }
}

---

4. Error Handling

• 400 Bad Request: Missing or invalid filters
• 401 Unauthorized: Invalid or missing access token
• 403 Forbidden: Missing stonal.document.read scope
• 404 Not Found: organizationCode not recognized

---

5. Best Practices

• Use UIDs whenever possible (identifier, assetIdentifiers) for precise, performant queries.
• Combine multiple filters to narrow down results (e.g., status + metadata + folder).
• Leverage linkedAsset for human-friendly searches when you don’t have exact UIDs.
• Tag and property filters are ideal for contextual grouping across documents.

For full API reference, see the Stonal API specification.