Delete Non-Batch Customers Guide

The DeleteCustomers endpoint removes customer profiles that are no longer relevant or valid in Optimove. It works only for customers registered through the Imported Customers feature, Optitrack, or the Upsert endpoints. It does not delete customers that were ingested through the Batch Process; those CIDs are rejected. You can delete up to 10,000 CIDs (customer IDs) in a single request, with a payload of up to 0.5 MB.

Common use cases:

• Visitor to registered customer — A visitor is first created in Optimove with a visitor ID. Later, the visitor registers and receives a new customer ID. Because Optimove may not know both IDs belong to the same person, you can delete the old visitor profile to avoid duplicates.
• Customer account consolidation — When you merge two customer accounts in your own system, delete the obsolete customer profile from Optimove.
• Incorrect customer creation — If an integration issue created profiles with incorrect IDs, delete those profiles after you fix the issue.

How It Works

In this guide, a batch means the list of CIDs you send in a single request.

The endpoint is asynchronous. A call that passes validation is acknowledged immediately with 202 Accepted. This does not mean the customers in the payload have been processed yet.

1. You send a batch of CIDs to POST /Customers/DeleteCustomers, optionally including a CallbackUrl.
2. Optimove validates the request envelope: batch size, payload size, and required fields. If the envelope is invalid, the request is rejected and nothing in it is processed.
3. A valid batch is accepted with 202 and queued for processing. The response body carries a TraceId.
4. Each CID in the batch is then processed individually and is either deleted or rejected.
5. When every customer in the batch has finished processing, Optimove sends a single status message to your CallbackUrl. No intermediate messages are sent for individual stages, including validation.

Example Response (202)

{
  "TraceId": "unique-trace-id"
}

⚠️

Without a CallbackUrl, you will not know what happened to your data
The 202 response confirms only that the batch was accepted. It says nothing about whether the customers in it were deleted or rejected.

That outcome is reported only in the status message sent to your CallbackUrl. If you do not supply one, the status message is never delivered, it is not stored, and there is no API for retrieving it afterwards. Supply a CallbackUrl on every call whose result matters to you.

Limits

• Batch limit: Up to 10,000 CIDs per call. A payload containing more than 10,000 CIDs is rejected in full.
• Size limit: The maximum payload size per call is 0.5 MB. A larger payload is rejected in full with 413 Payload Too Large.

Request

Endpoint

POST https://api4.optimove.net/Customers/DeleteCustomers (US)

POST https://api5.optimove.net/Customers/DeleteCustomers (EU)

Headers

The following headers are mandatory for all requests:

• X-API-KEY: Your Optimove API key.
• Content-Type: Must be set to application/json.

Request Body Parameters

The request body contains a list of CIDs and an optional callback URL.

Example

POST /Customers/DeleteCustomers
{
  "Customers": ["customer-id-1", "customer-id-2"],
  "CallbackUrl": "https://callback.url"
}

Here's a breakdown of the request body parameters:

Response Codes

Status Messages

When processing finishes, Optimove sends one status message to your CallbackUrl. Status messages for DeleteCustomers are different from status messages for UpsertCustomers.

Every status message includes an X-Action-Type header. For deletion, its value is Deletion. Upsert status messages set this header to Upsert, so you can use it to tell the two apart when both go to the same endpoint.

Example Status Message

{
  "status": "success",
  "traceId": "unique-trace-id",
  "totalCustomers": 1000,
  "deletedCustomers": 999,
  "rejectedCustomers": 1,
  "rejections": ["rejected-customer-id"]
}

Rejection Reasons

A CID is rejected for one of these reasons:

1. The customer was uploaded via the Batch Process.
2. The customer is being converted during the Batch Process.
3. The customer does not exist in Optimove.

Only customers registered via the Upsert API, the Optitrack SDK, or the Imported Customers feature can be deleted with this API. Customers ingested through the Batch Process cannot. The CIDs of all rejected customers are returned in the rejections field of the status message.

How Long Before a Customer Is Removed

Deletion is not reflected in Optimove immediately. How long it takes depends on where you check and on the request rate from your tenant.

Where to Check

Once a batch has been processed, you can find the customer on the Customer 360 page or in Customer Explorer.

Processing Time

Requests to this endpoint are queued and processed one after another, to support a high volume of concurrent requests. How long a request takes depends on your tenant's request rate:

• Low request rate — for example, one request roughly every minute rather than a continuous stream: a request can take up to 4 minutes from the moment you send the request until it is fully reflected in the system.
• Medium-to-high request rate — a constant, streamed flow of requests, which is where the system performs best. While total customers across all requests from your tenant stay under 20,000 per minute, a request is typically fully processed in about 1 minute. Each additional 2,000 CIDs above that threshold adds roughly 1 minute of wait time and can also delay subsequent requests.