Skip to main content
The GET /search API allows for filtering search results by their associated metadata. A mdfilters query parameter allows a developer to specify a metadata template and the desired values to query. 
curl -i -X GET "https://api.box.com/2.0/search?query=sales&mdfilters=%5B%7B%22scope%22%3A%22enterprise%22%2C%22templateKey%22%3A%22contract%22%2C%22filters%22%3A%7B%22category%22%3A%22online%22%7D%7D%5D" \
    -H "Authorization: Bearer <ACCESS_TOKEN>"
This example filters a search for any content that matches the query sales by any item that has enterprise.contract metadata attached to it and where the category field is set to online.

​
Introduction to Metadata

Metadata allows users and applications to define and store custom data associated with files and folders.
String field
Metadata consists of key/value pairs that are assigned to a file or a folder. For example, an important contract may have the key/value pairs of clientNumber: 820183 and category: online. The mdfilters query parameter allows developers to find files and folders that have a specific piece of metadata attached to them.

Learn more about metadata templates and instances

​
Metadata Filter Syntax

The mdfilters parameter can currently only contain one filter, although this may be expanded in the future. Each filter defines the scope and templateKey of the metadata template to filter on. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {}
  }
]
To get the scope and templateKey for a template, either list all metadata templates for an enterprise, or list all metadata instances on an item.
With the template defined, the filters field accepts a few different filter formats. The format of the filter very much depends on the type of field being filtered by.

​
Filter by string field

To filter by a field of type string a filter will need to define the key of the field and the desired value to find items for. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]
This example will find all files and folders that have an instance of the enterprise.contract template applied to it, and for which the field with the key category is set to the value online.

​
Filter by float field

To filter by a field of type float, you will need to define define a range by specifying a gt (greater-than) and/or lt (lower-than) value. To find an exact value, you can input the same value for both gt and lt. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "amount": {
        "gt": 10000,
        "lt": 20000
      }
    }
  }
]
This example will find all files and folders that have an instance of the enterprise.contract template applied to it, and for which the field with the key amount is set to a value equal or higher than 10000 and equal or lower than 2000. Note that gt and lt are inclusive and do not need to both be set.
If you create a query based on numbers, do not exceed the range of -16777215 and +16777215. For metadata search using number attributes the index value is stored as FLOAT32. As a result, integers between -16777215 and +16777215 can be precisely represented. Any operation with numbers beyond the range can lose its precision.

​
Filter by date field

To filter by a field of type date a filter will need to define the key of the field and the desired range to find items by specifying a gt (greater-than) and lt (lower-than) value. Please note that gt and lt are inclusive. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "expirationDate": {
        "gt": "2016-08-01T00:00:00Z",
        "lt": "2017-08-01T00:00:00Z"
      }
    }
  }
]
This example will find all files and folders that have an instance of the enterprise.contract template applied and have an expirationDate set to a date after or exactly 2016-08-01T00:00:00Z and before or exactly 2017-08-01T00:00:00Z.

​
Filter by enum field

To filter by a field of type enum a filter will need to define the key of the field and the desired value to find items for. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]
This example will find all files and folders that have an instance of the enterprise.contract template applied to it, and for which the field with the key category is set to the value online.

​
Filter by multiSelect field

To filter by a field of type multiSelect a filter will need to define the key of the field and any of the potential desired values to find items for. When performing a search, the query will essentially perform an OR operation to match any template where any of the provided values match this field. 
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": [
        "online",
        "enterprise"
      ]
    }
  }
]
This example will find all files and folders that have an instance of the enterprise.contract template applied to it, and for which the field with the key category is set to the value online or enterprise.