Remove Segment Users

Remove users from a manual segment with DELETE /v2/admin/segments/{segmentId}/users.

Removes users from a manual segment asynchronously. Unknown user names are skipped and listed in notFound. Users are not deleted from the project. Only segment membership is removed.

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

DELETEhttps://api.encatch.com/engage-product/encatch/api/v2/admin/segments/%7BsegmentId%7D/users

Authentication

X-Api-KeystringRequired

Admin (secret) API key

Content-TypestringRequired

Request body format

application/json

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.

Request body

Maximum body size: 512 KB (413 if larger).

userNamesstring[]Required

External user ids, 1–1000 values. Each 1–255 characters, no empty strings. Duplicates removed.

Examples

cURL

curl -X DELETE 'https://api.encatch.com/engage-product/encatch/api/v2/admin/segments/550e8400-e29b-41d4-a716-446655440000/users' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "userNames": ["alice@example.com"] }'

Success response

202Response

{
  "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "accepted": 1,
  "notFound": []
}

requestIdstringRequired

Correlation id for the remove operation.

acceptednumberRequired

Count of users queued to be removed.

notFoundstring[]Required

User names with no user in the project (skipped).

Errors

These are specific to Remove Segment Users. Shared errors include invalid or missing API key (401), publishable key on admin routes (403), rate limits (429), and sanitized 500 responses.

404Error

{
  "status": 404,
  "error": "Not Found",
  "message": "Segment not found"
}

Status	When
`400`	Invalid `userNames`
`404`	Segment not found
`409`	Not a manual segment (`Only manual segments can be changed through the API`)
`413`	Request body larger than 512 KB