POST /remove-users

This request bulk-removes the devices matching the given insider_ids from the segment of an activity previously created with /register:

• The removed users do not receive the push when /start is called.

• They are excluded from subsequent /update and /end messages.

• Idempotent: insider_ids that are not present in the segment (or already removed) are silently skipped (no error).

Unlike /add-users, /remove-users does not perform any eligibility filtering or profile lookup; it only deletes from the segment. Therefore, the partial, gdpr_denied_details, and unprocessed_insider_id_count fields never appear in the response.

This endpoint can be used only while the activity is in REGISTERED state. Once /start is called the segment is frozen and any /remove-users call is rejected with 409 ALREADY_STARTED.

Endpoint and headers

POST /api/v1/live-activity/remove-users

Headers

Body parameters

Below are the parameters for the request body.

• activity_type cannot be empty or whitespace-only.

• activity_id cannot be empty or whitespace-only.

• insider_ids must contain between 1 and 10,000 elements.

Sample body

Below is a sample body for a request.

{
  "activity_id": "550e8400-e29b-41d4-a716-446655440000",
  "activity_type": "DeliveryActivityAttributes",
  "insider_ids": [
    "user-12",
    "user-77"
  ]
}

Below is a typical usage:

T − 1 hour: /register is called for customers with active orders (Delivery activity_type). The activity is in the REGISTERED state.

T − 30 min: A customer cancels their order → the partner calls POST /remove-users and the devices belonging to that insider_id are removed from the segment.

T + 0: The partner calls /start → no push is sent to the canceling customer.

Sample responses

Success response 200

/add-users uses the same schema as /register. In practice, only removed and activity_id carry meaningful values. The other counters stay zero. partial, gdpr_denied_details, and unprocessed_insider_id_count fields never appear in the response.

{
  "status": "success",
  "activity_id": "550e8400-e29b-41d4-a716-446655440000",
  "matched": 0,
  "added": 0,
  "refreshed": 0,
  "removed": 2,
  "skipped": {
    "push_permission_disabled": 0,
    "unsupported_platform": 0,
    "unsupported_os_version": 0,
    "push_to_start_token_missing": 0,
    "user_not_found": 0
  }
}

Below are the fields that return in the response.

When no devices are removed

If none of the submitted insider_ids are present in the segment, the response is still 200 OK with removed: 0.

{
  "status": "success",
  "activity_id": "uuid",
  "matched": 0, "added": 0, "refreshed": 0, "removed": 0,
  "skipped": { "push_permission_disabled": 0, "unsupported_platform": 0,
               "unsupported_os_version": 0, "push_to_start_token_missing": 0,
               "user_not_found": 0 }
}

This is not an error; the endpoint is idempotent.

Error responses

Refer to Error Codes for details.

Limitations

• The rate limit is 1,000 requests per minute.

• Idempotent: insider_ids that are not present in the segment (or already removed) are silently skipped; no error is raised. The removed counter reflects only the devices actually deleted.

• No eligibility filtering: No profile lookup, no GDPR/iOS version/push opt-in check. The endpoint only performs an "ID match → delete" operation.

• removed may exceed the number of submitted insiders: If an insider has multiple devices in the segment, all of them are removed; removed is a device count, not an insider count.

• Not reversible: To put removed devices back, call /add-users (still before /start).