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. A custom field is indexed when it exists in the data entity and has isSearchable enabled, and nothing else is required to filter on it.
  • 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} 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}' does not exist for the data entity '{entity}'.Correct the field name in the filter.
400The field '{field}' of the data entity '{entity}' is not indexed (isSearchable is not enabled)... (truncated)Enable isSearchable on the field and wait for reindexing, or use another 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/{acronym}/delete

Request

  • Base URL
    https://apiexamples.vtexcommercestable.com.br
  • URL
    https://apiexamples.vtexcommercestable.com.br/api/dataentities/{acronym}/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

acronymstring required
Example:SP

Two-letter string that identifies 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

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 in the filter must be an internal field or a custom field with isSearchable enabled.

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