Remove All Users From Segment

Empty a manual segment with POST /v2/admin/segments/{segmentId}/users/remove-all while keeping the segment available.

Removes all existing users from a manual segment asynchronously. The segment remains available and can be filled again. Users are not deleted from the project, and their memberships in other segments are unchanged.

Users added at or after the removal request's timestamp are retained. Repeating this operation on an empty segment is supported.

Authenticate with an admin API key. Admin API rate limits apply separately from SDK limits.

POSThttps://api.encatch.com/engage-product/encatch/api/v2/admin/segments/{segmentId}/users/remove-all

Replace {segmentId} with your manual segment's UUID. For example, if the ID is 550e8400-e29b-41d4-a716-446655440000, the path is /v2/admin/segments/550e8400-e29b-41d4-a716-446655440000/users/remove-all. Do not include the braces in the actual request.

Authentication

X-Api-KeystringRequired

Admin (secret) API key for the project containing the segment.

The gateway determines the organization and project from the API key. You do not need to send X-Org-Id or X-Project-Id.

Publishable SDK keys receive 403 (publishable API keys cannot call /v2/admin routes).

Server-side only

Keep admin API keys on your server. Never ship them in client code.

Path parameters

segmentIdstringRequired

Manual segment UUID from Create Segment, List Segments, or the dashboard.

Request body

No request body is required. Do not send a list of user names; this operation removes all existing members.

Examples

Replace the example segment UUID and YOUR_ADMIN_API_KEY with your project's values. In JavaScript, Python, and Go, set ENCATCH_ADMIN_API_KEY in your server environment.

cURL

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/segments/550e8400-e29b-41d4-a716-446655440000/users/remove-all' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Accept: application/json'

Success response

202Response

{ "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }

requestIdstringRequired

Correlation id for the remove-all operation.

202 Accepted confirms that removal was queued. It does not mean processing has finished. Old membership records are cleaned up in the background.

Verify completion

Read the same segment with Get Segment:

cURL

curl 'https://api.encatch.com/engage-product/encatch/api/v2/admin/segments/550e8400-e29b-41d4-a716-446655440000' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY'

Expect 200 OK with memberCount equal to 0 after processing, provided no users were added afterward. If the count has not changed yet, wait a few seconds and check again. List Segments does not include member counts.

Errors

Shared errors include invalid or missing API key (401), publishable key on admin routes (403), rate limits (429), and sanitized 500 responses.

Status	When
`404`	Segment not found, deleted, or invalid UUID (`Segment not found`)
`409`	Not a manual segment (`Only manual segments can be changed through the API`)

Remove All Users From Segment

On this page