Add Segment Users

Add identified users to a manual segment with POST /v2/admin/segments/{segmentId}/users.

Adds users to a manual segment asynchronously. Users are not created. Only names that already exist in the project are queued. Unknown names and users already being deleted are skipped and listed in the response.

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/%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. Names sent exactly as stored (not trimmed).

Examples

cURL

curl -X POST '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", "bob@example.com"] }'

Success response

202Response

{
  "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "accepted": 1,
  "notFound": ["unknown@example.com"],
  "beingDeleted": []
}

requestIdstringRequired

Correlation id for the add operation.

acceptednumberRequired

Count of users queued to be added.

notFoundstring[]Required

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

beingDeletedstring[]

User names currently being deleted (skipped on add only).

Errors

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

400Error

{
  "status": 400,
  "error": "Bad Request",
  "message": "Missing required field: userNames"
}

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

Identify User: users must exist before they can be added
Remove Segment Users
Manual Segments