VTvtex
Bulk deletion

Create bulk document deletion job

Changed on

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 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.
  • 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 codeMessage or causeWhat to do
400The 'filter' field is required.Send the filter field in the body.
400Wildcard filters are not allowed for bulk delete.Rewrite the filter using exact or range conditions over indexed fields.
400The 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.
400The 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.
400Invalid data entity name.Correct the data entity name in the URL. Invalid characters are rejected.
400The 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.
409Bulk 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.
415The Content-Type: application/json header is missing or the media type is not supported.Send the Content-Type: application/json header.
5xxTransient 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, sent in the VtexIdclientAutCookie header.

post/api/dataentities/{dataEntityName}/delete

Request

  • Base URL
    https://apiexamples.vtexcommercestable.com.br
  • URL
    https://apiexamples.vtexcommercestable.com.br/api/dataentities/{dataEntityName}/delete
  • Auth
    • API key in header X-VTEX-API-AppKey and API key in header X-VTEX-API-AppToken
    • or API key in header VtexIdclientAutCookie

Path parameters

dataEntityNamestring required
Example:Newsletter

Name of the data entity.

Query parameters

anstring required
Example:apiexamples

Name of the VTEX account that owns the data entity (for example, apiexamples).

Headers

Content-Typestring required
Example:application/json

Type of the content being sent.

Request body

filterstring required

Deletion criteria, using the same syntax as the filter in the Search documents request. Wildcards are not allowed and every field must be indexed.

schemastring

Name of the schema that declares the filtered field as indexed. Required only when the filter uses custom fields.

Response

Accepted

JobIdstring

Unique identifier of the bulk deletion job. Use this value to track the job with the Get bulk document deletion job status endpoint.

Changes