--- title: "Create bulk document deletion job" method: POST path: "/api/dataentities/{dataEntityName}/delete" tags: ["Bulk deletion"] --- # Create bulk document deletion job `POST /api/dataentities/{dataEntityName}/delete` ## Request - Base URL: `https://apiexamples.vtexcommercestable.com.br` - URL: `https://apiexamples.vtexcommercestable.com.br/api/dataentities/{dataEntityName}/delete` - Auth: one of: - API key in header `X-VTEX-API-AppKey` and API key in header `X-VTEX-API-AppToken` - API key in header `VtexIdclientAutCookie` Creates an asynchronous job that deletes all documents in a data entity that match a given filter. This request does not delete any documents by itself. It creates a job and returns a `JobId`, which you must use to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/delete/jobs/-jobId-) endpoint. >❗ This action cannot be undone. Deleted documents will be permanently lost. ## Filter rules - The `filter` field is required. - Wildcards are not allowed. For example, `email = *@gmail.com` is rejected. - Every field used in the filter must be indexed. Internal fields, such as `createdIn`, are already indexed. - Filtering on a custom field also requires sending the `schema` that declares it as indexed in the request body. A custom field is declared as indexed for filtering in the `v-indexed` array of its [schema](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-). - Only one active job per account and data entity is allowed at a time. >ℹ️ Confirm how many documents match your filter before deleting them, so you can compare that number with the `DocumentsDeleted` value returned by the job status endpoint. ## Errors `{field}`, `{schema}`, and `{entity}` are placeholders for values from your request, and any quotation marks around them are part of the message returned by the API. Messages marked as truncated continue beyond the text shown. | Status code | Message or cause | What to do | | - | - | - | | `400` | `The 'filter' field is required.` | Send the `filter` field in the body. | | `400` | `Wildcard filters are not allowed for bulk delete.` | Rewrite the filter using exact or range conditions over indexed fields. | | `400` | `The field '{field}' is not an internal indexed field, so the 'schema' that declares it as indexed must be provided.` | Send the `schema` field in the body. | | `400` | `The field '{field}' is not indexed in the schema '{schema}'...` (truncated) | Mark the field as indexed in the schema and wait for reindexing, or filter on an already indexed field. | | `400` | `Invalid data entity name.` | Correct the data entity name in the URL. Invalid characters are rejected. | | `400` | The request body is empty or is not valid JSON. This response uses the standard validation error format and does not include the `Message` field. | Send a valid JSON body. | | `409` | `Bulk deletion job creation failed for entity {entity}`, returned when a job is already `InProgress` for this account and data entity. | Track the existing job and resend once its status is `Success` or `Failed`. If a job appears stuck, the data entity automatically accepts new jobs after 12 hours. | | `415` | The `Content-Type: application/json` header is missing or the media type is not supported. | Send the `Content-Type: application/json` header. | | `5xx` | Transient infrastructure failure during job creation. | No residual state is left behind, so you can resend the request. | ## Permissions This request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header. ## Path parameters - `dataEntityName` string, required ## Query parameters - `an` string, required ## Headers - `Content-Type` string, required ## Request body - BulkDeletionRequest: Request body object. - `filter` string, required: Deletion criteria, using the same syntax as the filter in the [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) request. Wildcards are not allowed and every field must be indexed. - `schema` string: Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that declares the filtered field as indexed. Required only when the filter uses custom fields. ## Response `202` Accepted - BulkDeletionJobResponse: Response body object. - `JobId` string: Unique identifier of the bulk deletion job. Use this value to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/delete/jobs/-jobId-) endpoint. ## Other responses - `400`: Bad Request - `409`: Conflict - `415`: Unsupported Media Type Returned when the JSON content type header is missing or the media type is not supported. - `500`: Internal Server Error ## Changes - **2026-09-02** `8abe82281c5c`: 1 info - endpoint added - **2026-05-14** `6d3f8010fa54`: 1 breaking - api path removed without deprecation - **2026-04-08** `4d580ec5be53`: 1 info - endpoint added [Operation history](https://skmtc.dev/vtex/apis/master-data-api-v2/changes/api/dataentities/:dataEntityName/delete/post.md) --- [API](https://skmtc.dev/vtex/apis/master-data-api-v2.md) - [All operations](https://skmtc.dev/vtex/apis/master-data-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/vtex/apis/master-data-api-v2/revisions/4d580ec5be53?raw)