Create an Event Delete or Update Request

Event Delete & Update is available through three API endpoints: one to delete a single event, one to update a single event, and one to export a daily audit of all operations. This page walks through all three endpoints with authentication, field references, and request examples built around a single running scenario so you can follow the data end-to-end.

Endpoint and Headers

POST https://unification.useinsider.com/api/user/v1/delete-single-event

Headers

Every request to the Event Delete & Update endpoints must include the following headers.

Running scenario

Every example on this page uses the same scenario. A passenger booked a flight to Paris through your mobile app. The passenger later changed the trip to Istanbul. The booking is real, but the destination on the original event is outdated. You will see how to delete a duplicate event and how to update the booking with the corrected destination, price, and currency.

Scenario reference

• Event name: booking_completed

• Source: web

• Business identifier: booking_id: "BKG-9821"

• Parameters on the event: destination, total_price, currency, promo_code

1. Delete a single event

Use this endpoint when an event exists in the system but should not; it was fired by mistake, is a duplicate, or was a test event that landed on a real user profile. The endpoint locates exactly one matching event, removes it, and triggers automatic re-evaluation of journeys, segments, and analytics.

Endpoint

POST https://unification.useinsider.com/api/user/v1/delete-single-event

Body Parameters

Sample Request: Delete by timestamp and source

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/delete-single-event' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "identifiers": { "email": "passenger@example.com" },
    "event_name": "booking_completed",
    "source": "web",
    "timestamp": "2026-03-15T10:00:02Z",
    "hook_url": "https://example.com/hooks/event-delete"
  }'

Sample Request: Delete by business identifier

When the exact timestamp is not available, identify the event using a business identifier in the filters field instead.

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/delete-single-event' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "insider_id": "iid-12345",
    "event_name": "booking_completed",
    "filters": {
      "booking_id": "BKG-9821"
    }
  }'

Sample Responses

202 Accepted

{
  "operation_id": "f3c5e6a8-1d24-4b6f-90c1-2a5b9c8e7d44",
  "status": "accepted"
}

202 confirms acceptance, not completion.

The operation runs asynchronously. Set hook_url to receive the final outcome, success, failure, or skip, once execution completes.

Deleted events are not recoverable:

Validate your identifier and filters against the target event before sending the request. If the combination matches more than one event, the request is rejected and no change is applied. If the event does not exist, the API returns 400 with "event does not exist" and no operation record is created.

2. Update a single event

Use this endpoint when an event should remain in the system, but one or more of its parameters are outdated. The endpoint applies a PATCH-style update; only the parameters listed in update_params change. All other parameters on the event remain untouched.

Endpoint

POST https://unification.useinsider.com/api/user/v1/update-single-event

Update semantics

Update follows a PATCH model. For each key in update_params: sending a value replaces the current value; sending null either sets the parameter to NULL or removes it entirely, depending on the delete_null flag; omitting a key leaves the parameter unchanged. Event timestamps cannot be changed via update.

Understanding delete_null

delete_null is a single request-level flag that controls what happens when a parameter is sent as null in update_params. It does not affect non-null values; non-null values always replace the current value regardless of this setting.

Body Parameters

Sample Request: Replace parameter values

Correct the destination, total price, and currency on the booking event in a single call.

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/update-single-event' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "identifiers": { "email": "passenger@example.com" },
    "event_name": "booking_completed",
    "source": "web",
    "timestamp": "2026-03-15T10:00:02Z",
    "skip_hook": true,
    "update_params": {
      "destination": "Istanbul",
      "total_price": 1299.50,
      "currency": "EUR"
    }
  }'

Sample Request: Remove a parameter entirely

A promo code was attached to the booking by mistake. Set delete_null to true and send the parameter as null to remove it from the event entirely.

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/update-single-event' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "insider_id": "iid-12345",
    "event_name": "booking_completed",
    "filters": { "booking_id": "BKG-9821" },
    "delete_null": true,
    "update_params": {
      "promo_code": null
    }
  }'

Sample Request: Replace values and remove a parameter in the same call

Correct currency and total_price, and remove promo_code, in one request. With delete_null: false, non-null values are replaced and the null value removes the parameter.

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/update-single-event' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "identifiers": { "email": "passenger@example.com" },
    "event_name": "booking_completed",
    "filters": { "booking_id": "BKG-9821" },
    "delete_null": false,
    "update_params": {
      "currency": "EUR",
      "total_price": 1299.50,
      "promo_code": null
    }
  }'

Sample Responses

202 Accepted

{
  "operation_id": "a91d7c12-58f2-4d09-83c5-6f2eaa9c3b71",
  "status": "accepted"
}

Keys in update_params must be mapped event parameters.

Unmapped keys are rejected with 400. Values must match the parameter data type; type mismatches are rejected with "Data type mismatch". Event timestamps cannot be updated.

Response codes

The following response codes apply to the delete and update endpoints:

3. Export operations history

Use this endpoint to retrieve a daily audit of every delete and update operation that ran for your account on a given calendar day. The request is accepted synchronously and returns a request_id immediately. The export file and a summary are delivered asynchronously to your webhook URL once ready.

Endpoint

POST https://unification.useinsider.com/api/raw/v1/operations-export

Body Parameters

Sample Request

To export all successful update operations for 15 March 2026:

curl --location --request POST 'https://unification.useinsider.com/api/raw/v1/operations-export' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'X-API-KEY: bearer-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "date": "2026-03-15",
    "status": "success",
    "operation_type": "update",
    "hook_url": "https://example.com/hooks/ops-export"
  }'

Sample Responses

Sync response

202 Accepted

{
  "request_id": "9d4b2a6e-1f3c-4f2d-8d5e-7b9c0a1234ef"
}

Async webhook payload: Success

Once the export is ready, Insider One POSTs the following to your hook_url. The download URL is a time-limited signed link and expires in 24 hours, so download the file promptly.

{
  "request_id": "9d4b2a6e-1f3c-4f2d-8d5e-7b9c0a1234ef",
  "partner": "mybrand",
  "status": "success",
  "url": "https://insider-exports.s3.amazonaws.com/...signed-url...",
  "date": "2026-03-15",
  "operation_type": "update",
  "summary": {
    "total_operations": 1284,
    "delete_count": 0,
    "update_count": 1284,
    "success_count": 1271,
    "failed_count": 13
  }
}

Async webhook payload: Export failure

{
  "request_id": "9d4b2a6e-1f3c-4f2d-8d5e-7b9c0a1234ef",
  "partner": "mybrand",
  "status": "failed",
  "message": "internal error generating export"
}

Sync error codes

Rate limit for this endpoint is separate.

The operations export endpoint allows 3 requests per hour. This is independent of the 250 requests per minute limit shared across the delete and update endpoints.

Limitations

• API only. There is no panel interface for delete or update in this version.

• One event, one user per request. Each request targets exactly one event on one user profile. Bulk operations are not supported.

• One event type per request. To correct more than one event type, send separate requests.

• Filter and parameter limits. Up to 50 entries in filters and up to 50 entries in update_params per request.

• Timestamps are immutable. Event timestamps cannot be changed via update.

• Operations are not reversible. Validate filters before sending.

• Rate limit. 250 requests per minute per partner, shared across delete and update. The export endpoint has a separate limit of 3 requests per hour.

• Payload size. Up to 5 MB per request.

• Identifier resolution is read-only. If the identifier is unknown, the request returns a 400 response. No new user profile is created on this path.

• Excluded events cannot be targeted. See the Excluded Events section below.

Excluded events

Some events are managed directly by the Insider One platform, and they reflect message delivery, session state, and other operational signals that must remain consistent for Architect, segmentation, and analytics to function correctly. These events cannot be deleted or updated through the API. Requests targeting them return 400 with "excluded by platform integrity policy".

All custom events, anything not listed in the table below, remain eligible for delete and update.