User Segments REST API

Create manually updated list-based segments and override, append, or remove members by segment ID.

General

• Requests and responses use JSON encoded in UTF-8.
• The full endpoint URL is the data center Base URL plus the API path. See REST API Overview for how to obtain the Base URL and API Key / API Secret.
• Use HTTP Basic Authentication: Authorization: Basic ${base64(api_key:api_secret)}. The API data source bound to the API Key determines the project; callers do not pass a project ID in the request body.
• Successful responses share a common structure: code 0 means success, message describes the result, and data carries the payload. Batch handling for member writes depends on the operation: OVERRIDE runs only after all batches are received; each batch of APPEND and REMOVE is applied independently. data.status and data.complete in the response indicate processing state.

Create a list-based segment

Creates a segment with manual update mode and list upload as the creation method. The segment has no members after creation; use Update segment members to upload the list.

Endpoint

POST /v1/segments

Request example

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "High-value users",
    "description": "High-value user list synced from the order system"
  }'

            

Request parameters

Response example

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "High-value users",
    "generation": "generation-1"
  }
}

            

Update segment members

A single endpoint overrides, appends, or removes list members. Only segments in the current project that were created via list upload, use manual update, and are active are accepted. User identifiers must match existing active users in the project; the API does not create user assets. When the segment does not qualify, errors 55210–55214 are returned (see Error responses).

Endpoint

POST /v1/segments/{segmentId}/members

Request example

The following example splits one OVERRIDE operation into two batches. Each batchId represents one list operation; all batches must use the same batchId, operation, and batchCount. OVERRIDE applies the list change only after all batches are received. APPEND and REMOVE take effect as soon as each batch request succeeds.

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "batchIndex": 0,
    "batchCount": 2,
    "members": [
      {"euid": "100001"},
      {"identityName": "user_id", "identityValue": "user-002"}
    ]
  }'

            

When the first OVERRIDE batch is received, status in the response is RECEIVING and complete is false. Submit the remaining batch with the same batchId and set batchIndex to 1.

Request parameters

members elements support the following two formats; euid cannot be sent together with identityName / identityValue:

List operations

Retries with the same batchId must use the same operation, batchCount, and batch content; the same batchId and batchIndex cannot carry different content. Idempotent results are kept for 24 hours.

OVERRIDE batches are held until all are received, then applied; held data expires after a 24-hour TTL, and the list is not changed if batches are incomplete before expiry. Each APPEND and REMOVE batch applies independently; batchCount and batchIndex still identify batches, support idempotency, and track progress without blocking the current batch.

Each successful list change is recorded in segment update history with source REST API. OVERRIDE is logged per completed batch; APPEND and REMOVE per successful batch. Audit records do not include samples of unmatched or invalid identifiers.

Response examples

Batch not yet complete:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "RECEIVING",
    "complete": false,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 2,
    "unmatchedCount": 0,
    "unmatchedSamples": [],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 0,
    "exitCount": 0
  }
}

            

OVERRIDE batch completed:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 2,
    "inputCount": 3,
    "matchedCount": 2,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 1,
    "invalidSamples": [
      {"identityName": "not_configured", "identityValue": "example"}
    ],
    "invalidSamplesTruncated": false,
    "enterCount": 2,
    "exitCount": 1
  }
}

            

When an APPEND or REMOVE batch succeeds, the current batch applies immediately and returns complete: true even if batchCount is greater than the number of batches received so far. For example, with batchCount 2 and only the first batch received, receivedBatchCount is 1 and status is COMPLETED.

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-append",
    "operation": "APPEND",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 1,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 1,
    "exitCount": 0
  }
}

            

Samples follow the member identifier object structure from the request and may include the submitted identityValue. The server stores samples only in the 24-hour idempotency cache, not in audit records; handle responses and logs per your data compliance requirements.

If the response is PROCESSING, retry with the same batchId, batchIndex, and original batch content for an idempotent result. There is no separate batch progress query API.

Error responses

Errors use code and message; see HTTP Status Codes for HTTP status codes and general return codes.

When creating a segment, business error codes and message from Metadata are passed through to the caller, e.g. duplicate name 40026, limit 40032. On the list upload path, “segment does not exist” returns 55201 instead of 40027.

Unmatched or invalid member identifiers do not fail the whole list operation (except OVERRIDE when no users match; see 55214). The response returns counts and up to 100 identifier samples. Samples may include identityValue; protect response data accordingly.