用户分群 REST API | Marketing Automation REST API 简体中文

创建手动更新的名单分群，并按分群 ID 覆盖、追加或移除成员。

通用说明

请求和响应均使用 UTF-8 编码的 JSON。
完整调用地址由数据中心的 Base URL 与接口路径组成。Base URL 和 API Key / API Secret 的获取方式请参见 REST API 概述。
使用 HTTP Basic Authentication：Authorization: Basic ${base64(api_key:api_secret)}。API Key 对应的 API 数据源决定所属项目，调用方不需要在请求体中传入项目 ID。
成功响应使用统一结构：code 为 0 表示成功，message 为结果描述，data 为接口数据。成员写入的分片处理规则取决于操作类型：OVERRIDE 收齐全部分片后才执行；APPEND 和 REMOVE 的每个分片独立执行。响应中的 data.status 和 data.complete 表示当前处理状态。

创建名单分群

创建一个更新方式为手动、创建方式为名单上传的分群。分群创建后成员为空，可使用「更新分群成员」接口写入名单。

调用地址

POST /v1/segments

请求示例

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": "高价值用户", "description": "通过订单系统同步的高价值用户名单" }'

              
              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": "高价值用户",
    "description": "通过订单系统同步的高价值用户名单"
  }'

此代码块在浮窗中显示

请求参数

字段	类型	必填	描述
`name`	String	是	分群名称，不能为空，最多 50 个字符；同一项目内不能重名。首尾空格会被去除。
`description`	String	否	分群描述，最多 200 个字符。

返回示例

{ "code": 0, "message": "success", "data": { "segmentId": 123456789, "name": "高价值用户", "generation": "generation-1" } }

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "高价值用户",
    "generation": "generation-1"
  }
}

此代码块在浮窗中显示

字段	类型	描述
`segmentId`	Long	新建分群 ID，后续名单写入时使用。
`name`	String	分群名称。
`generation`	String	当前成员版本标识。新建分群的成员为空。

更新分群成员

通过单一接口覆盖、追加或移除名单。接口只接受当前项目中创建方式为名单上传、更新方式为手动且状态为生效中的分群。用户标识必须能匹配到项目中已有的可用用户；接口不会创建用户资产。不满足分群条件时返回 55210–55214（见错误响应），可直接定位原因。

调用地址

POST /v1/segments/{segmentId}/members

请求示例

以下示例把一次 OVERRIDE 操作拆成两个分片。每个 batchId 表示一项名单操作；所有分片必须使用相同的 batchId、operation 和 batchCount。OVERRIDE 收齐全部分片后才执行名单变更。APPEND 和 REMOVE 则会在各自分片请求成功时立即生效。

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"} ] }'

              
              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"}
    ]
  }'

此代码块在浮窗中显示

收到第一个 OVERRIDE 分片时，响应中的 status 为 RECEIVING、complete 为 false。提交剩余分片时使用相同的 batchId，并将 batchIndex 设置为 1。

请求参数

字段	类型	必填	描述
`segmentId`	Long	是	路径参数，目标分群 ID。
`batchId`	String	是	一次完整名单操作的批次 ID，长度不超过 128 个字符，只能包含英文字母、数字、点、下划线、冒号和连字符。同一项目、同一分群下 24 小时内作为幂等标识使用。
`operation`	String	是	名单操作：`OVERRIDE`（覆盖）、`APPEND`（追加）、`REMOVE`（移除）。
`batchIndex`	Integer	是	当前分片序号，从 `0` 开始，且必须小于 `batchCount`。
`batchCount`	Integer	是	此次操作的分片总数，范围为 1–10。所有分片合计最多 10,000 个成员标识。
`members`	Array	是	当前分片的成员标识，不能为空，每片最多 1,000 个。每个元素使用下表中的一种标识格式。

members 元素支持以下两种格式，euid 不能与 identityName / identityValue 同时传入：

字段	类型	描述
`euid`	String	项目内 EUID，须为正整数格式，例如 `"100001"`。
`identityName`	String	项目中已配置的用户标识名称，不能为空，最多 128 个字符。
`identityValue`	String	用户标识值，不能为空，最多 256 个字符；与 `identityName` 配套使用。超过 256 个字符不会整单失败，该行计入 `invalidCount`。

名单操作说明

操作	说明
`OVERRIDE`	收齐全部分片后，以本次提交且匹配成功的用户替换现有名单。若匹配到的可用用户为空，整单拒绝并返回 `55214`，现有名单不变。
`APPEND`	当前分片请求成功后，将其中匹配成功的用户追加到现有名单；已在群用户不会重复加入。无需等待其他分片。
`REMOVE`	当前分片请求成功后，从现有名单移除其中匹配成功的用户；不在群用户不会产生额外变更。无需等待其他分片。

batchId 相同的重试必须提交相同的操作、batchCount 和分片内容；同一 batchId、同一 batchIndex 不可提交不同内容。幂等结果保留 24 小时。

OVERRIDE 的分片会暂存至全部收齐后再执行；暂存数据按 24 小时 TTL 过期，过期前未收齐时不会变更名单。APPEND 和 REMOVE 的每个分片独立生效，batchCount 和 batchIndex 仍用于分片标识、幂等和进度统计，不会阻止当前分片执行。

每次成功的名单变更会在分群更新记录中留下来源为 REST API 的记录。OVERRIDE 按完成的批次记录，APPEND 和 REMOVE 按成功分片记录；审计记录不包含未匹配或无效标识值样例。

返回示例

分片尚未收齐：

{ "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 } }

              
              {
  "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 批次处理完成：

{ "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 } }

              
              {
  "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
  }
}

此代码块在浮窗中显示

APPEND 或 REMOVE 分片成功时，即使 batchCount 大于已收到的分片数，当前分片仍会立即生效并返回 complete: true。例如，batchCount 为 2、当前只收到第一个分片时，响应中的 receivedBatchCount 为 1，status 为 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 } }

              
              {
  "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
  }
}

此代码块在浮窗中显示

字段	类型	描述
`batchId`	String	本次名单操作的批次 ID。
`operation`	String	本次名单操作。
`status`	String	`RECEIVING`：`OVERRIDE` 等待分片；`PROCESSING`：当前请求等待名单变更锁；`COMPLETED`：当前操作已完成。
`complete`	Boolean	`OVERRIDE` 表示全部分片已应用；`APPEND`/`REMOVE` 表示当前分片已应用，不代表所有分片都已提交。
`expectedBatchCount`	Integer	预期分片总数。
`receivedBatchCount`	Integer	已收到的不同分片序号数量；对于 `APPEND`/`REMOVE`，该值仅用于统计，不影响当前分片执行。
`inputCount`	Integer	有效输入行数 = `matchedCount` + `unmatchedCount`，不含无效标识。`OVERRIDE` 统计已收到分片（完成时为整个批次）；`APPEND`/`REMOVE` 统计当前分片。
`matchedCount`	Integer	匹配到可用用户的标识数。
`unmatchedCount`	Integer	未匹配到可用用户的标识数。
`unmatchedSamples`	Array	未匹配标识样例，元素结构与请求的成员标识相同，最多返回 100 条。
`unmatchedSamplesTruncated`	Boolean	未匹配样例是否因 100 条上限而截断。
`invalidCount`	Integer	无效标识数，不计入 `inputCount`。包括：`euid` 非正整数、与 identity 字段同传、`identityName`/`identityValue` 为空或不配套、`identityName` 超过 128 字符、`identityValue` 超过 256 字符、标识名未在项目中配置、同一标识匹配到多个可用用户。
`invalidSamples`	Array	无效标识样例，元素结构与请求的成员标识相同，最多返回 100 条。
`invalidSamplesTruncated`	Boolean	无效样例是否因 100 条上限而截断。
`enterCount`	Integer	本次执行实际新增的在群用户数。
`exitCount`	Integer	本次执行实际移出分群的用户数。

样例沿用请求中的成员标识对象结构，可能包含传入的 identityValue。服务端仅在 24 小时幂等结果缓存中暂存样例，不会将其写入审计记录；请按自身数据合规要求处理响应及日志。

如果响应为 PROCESSING，可使用相同 batchId、batchIndex 和原分片内容重试，取得幂等结果。该接口没有独立的批次进度查询接口。

错误响应

错误响应仍使用 code 和 message 字段；HTTP 状态码及通用返回码说明请参见 HTTP 状态码。

HTTP 状态码	返回码	描述
401	`40050`	API Key / API Secret 鉴权失败，或 API 数据源已禁用。
400	`40026`	当前项目中已存在同名用户分群（创建路径，Metadata 透传）。
400	`40032`	用户分群数量已达上限（创建路径，Metadata 透传）。
400	`55201`	用户分群不存在（名单写入路径）。
400	`55210`	分群创建方式不支持 REST API 名单写入：目标分群不是名单上传创建（如规则创建的分群）。
400	`55211`	分群更新方式不支持 REST API 名单写入：目标分群不是手动更新。
400	`55212`	分群当前生命周期状态不支持 REST API 名单写入：目标分群不在生效中。
400	`55213`	分群当前没有可用成员版本，暂不支持 REST API 名单写入。
400	`55214`	不允许用空名单覆盖分群：`OVERRIDE` 收齐后匹配到的可用用户为空。
400	`55004`	请求字段或名单批次参数不符合要求。
503	`55207`	分群元数据暂不可用。
500	`55000`	服务端内部错误。

创建分群时，Metadata 返回的业务错误码和 message 会透传给调用方，例如同名 40026、数量达上限 40032。名单写入路径的「分群不存在」返回 55201，不再使用 40027。

未匹配或无效的成员标识不会导致名单操作整体失败（OVERRIDE 在匹配用户为空时除外，见 55214）。响应会同时返回数量和最多 100 条标识样例。样例可能包含 identityValue，请妥善保护响应数据。