---
title: "Search documents"
method: GET
path: "/api/dataentities/{acronym}/search"
tags: ["Search"]
---

# Search documents

`GET /api/dataentities/{acronym}/search`

Retrieves Master Data v1 documents' information, while choosing which fields will be returned and filtering documents by specific fields.

>ℹ️ Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api) and [Querying documents in Master Data v1](https://developers.vtex.com/docs/guides/querying-documents-in-master-data-v1).

## Query examples


| **Filter Type** | **Example** |
|-|-|
| **Simple filter** | `/dataentities/CL/search?email=my@email.com` |
| **Complex filter** | `/dataentities/CL/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |
| **Date range** | `/dataentities/CL/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |
| **Numeric field range**     | `/dataentities/CL/search?_where=age between 18 AND 25` |
| **Partial filter** | `/dataentities/CL/search?firstName=*Maria*` |
| **Null values** | `/dataentities/CL/search?_where=firstName is null` |
| **Non-null values** | `/dataentities/CL/search?_where=firstName is not null` |
| **Difference** | `/dataentities/CL/search?_where=firstName<>maria` |
| **Greater than** | `/dataentities/CL/search?_where=number>5` |
| **Less than** | `/dataentities/CL/search?_where=date<2001-01-01` |


>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`. 

## Permissions

Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |
| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |
| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |
| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |

There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

## Path parameters

- `acronym` string, required

## Query parameters

- `_fields` string
- `_where` string
- `_sort` string

## Headers

- `Content-Type` string, required
- `Accept` string, required
- `REST-Range` string, required

## Response `200`

OK

- object[] — List of documents.
  - `additionalProperties` string — Custom properties.
  - `id` string — Unique identifier of the document.
  - `accountId` string — Unique identifier of the account.
  - `accountName` string — Account name.
  - `dataEntityId` string — Two-letter string that identifies the data entity.

## Other responses

- `503` — Service Unavailable Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.

---

[API](https://skmtc.net/vtex/apis/master-data-api-v1.md) · [All operations](https://skmtc.net/vtex/apis/master-data-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vtex/master-data-api-v1/revisions/a90298d4afb1/schema)