Create Segment

Creates a manual segment asynchronously. The response includes segmentId, which you can read with Get Segment once the consumer has written the row (usually within seconds). A 404 immediately after create means the segment is not written yet.

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

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.

Request body

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

namestringRequired

Segment name, 1–250 characters after trimming leading and trailing whitespace.

descriptionstring

Optional description, up to 1000 characters after trimming. Defaults to empty.

Examples

cURL

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/segments' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Beta testers",
    "description": "Invited to product feedback"
  }'

Success response

202Response

{
  "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "segmentId": "550e8400-e29b-41d4-a716-446655440000"
}

requestIdstringRequired

Correlation id for the create operation.

segmentIdstringRequired

UUID of the new segment. Readable with GET once applied.

Errors

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

402Error

{
  "status": 402,
  "error": "Payment Required",
  "message": "You have reached your Segments limit. Your plan allows 5. You currently have 5 segments in this project."
}

Status	When
`400`	Missing or empty `name`; `name` or `description` too long
`402`	Segment plan limit reached (`Segments are not available on your current plan` or `You have reached your Segments limit…`)
`413`	Request body larger than 100 KB