ユーザーセグメント REST API | Marketing Automation REST API 日本語

手動更新のリストベースセグメントを作成し、セグメント ID ごとにメンバーを上書き、追加、または削除します。

共通事項

リクエストとレスポンスは UTF-8 でエンコードされた JSON を使用します。
完全なエンドポイント URL は、データセンターの Base URL と API パスを組み合わせたものです。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": "High-value users", "description": "High-value user list synced from the order system" }'

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

このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

フィールド	タイプ	必須	説明
`name`	String	はい	セグメント名。空にできず、最大 50 文字。プロジェクト内で一意である必要があります。先頭と末尾の空白はトリムされます。
`description`	String	いいえ	セグメントの説明。最大 200 文字。

レスポンス例

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

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

このコードブロックはフローティングウィンドウ内に表示されます

フィールド	タイプ	説明
`segmentId`	Long	新規セグメントの ID。以降のリストアップロードで使用します。
`name`	String	セグメント名。
`generation`	String	現在のメンバー世代識別子。新規作成セグメントにはメンバーがありません。

セグメントメンバーを更新

単一エンドポイントでリストメンバーを上書き、追加、または削除します。現在のプロジェクト内で、リストアップロードにより作成され、手動更新で、有効なセグメントのみ受け付けます。ユーザー識別子はプロジェクト内の既存の有効なユーザーと一致する必要があり、API はユーザーアセットを作成しません。セグメントが条件を満たさない場合、エラー 55210–55214 が返されます（エラーレスポンスを参照）。

エンドポイント

POST /v1/segments/{segmentId}/members

リクエスト例

次の例では、1 回の OVERRIDE 操作を 2 つのバッチに分割しています。各 batchId は 1 回のリスト操作を表します。すべてのバッチで同じ 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	はい	1 回の完全なリスト操作のバッチ ID。最大 128 文字。英字、数字、ドット、アンダースコア、コロン、ハイフンのみ。プロジェクトおよびセグメントごとに 24 時間以内の冪等キーとして使用されます。
`operation`	String	はい	リスト操作：`OVERRIDE`（置換）、`APPEND`（追加）、`REMOVE`（削除）。
`batchIndex`	Integer	はい	現在のバッチのインデックス。`0` から開始し、`batchCount` 未満である必要があります。
`batchCount`	Integer	はい	この操作のバッチ総数。1–10。すべてのバッチを合わせて最大 10,000 件のメンバー識別子。
`members`	`Array<Object>`	はい	現在のバッチのメンバー識別子。空にできず、バッチあたり最大 1,000 件。各要素は下表のいずれかの形式を使用します。

members 要素は次の 2 形式をサポートします。euid は identityName / identityValue と同時に送信できません：

フィールド	タイプ	説明
`euid`	String	プロジェクト EUID。正の整数文字列である必要があります（例：`"100001"`）。
`identityName`	String	プロジェクトで設定されたユーザー識別名。空にできず、最大 128 文字。
`identityValue`	String	識別子の値。空にできず、最大 256 文字。`identityName` と組み合わせて使用します。256 文字を超えてもリクエスト全体は失敗せず、該当行は `invalidCount` に計上されます。

リスト操作

操作	説明
`OVERRIDE`	すべてのバッチを受信した後、今回の送信で一致したユーザーで現在のリストを置き換えます。有効なユーザーが 1 件も一致しない場合、リクエストは `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	受信した distinct なバッチインデックス数。`APPEND`/`REMOVE` では統計のみに使用し、現在のバッチをブロックしません。
`inputCount`	Integer	有効入力行数 = `matchedCount` + `unmatchedCount`（無効識別子は含まない）。`OVERRIDE` は受信バッチを集計（完了時はバッチ全体）；`APPEND`/`REMOVE` は現在のバッチを集計。
`matchedCount`	Integer	有効なユーザーに一致した識別子数。
`unmatchedCount`	Integer	有効なユーザーに一致しなかった識別子数。
`unmatchedSamples`	`Array<Object>`	一致しなかった識別子のサンプル。リクエストメンバーと同じ構造。最大 100 件。
`unmatchedSamplesTruncated`	Boolean	一致しなかったサンプルが 100 件で切り詰められたか。
`invalidCount`	Integer	無効識別子数。`inputCount` に含まれません。含まれる例：非正整数の `euid`、`euid` と identity フィールドの同時送信、空または不整合の `identityName`/`identityValue`、`identityName` が 128 文字超、`identityValue` が 256 文字超、未設定の識別名、1 識別子が複数の有効ユーザーに一致。
`invalidSamples`	`Array<Object>`	無効識別子のサンプル。リクエストメンバーと同じ構造。最大 100 件。
`invalidSamplesTruncated`	Boolean	無効サンプルが 100 件で切り詰められたか。
`enterCount`	Integer	今回の実行でセグメントに実際に追加されたユーザー数。
`exitCount`	Integer	今回の実行でセグメントから実際に削除されたユーザー数。

サンプルはリクエストのメンバー識別子オブジェクト構造に従い、送信した identityValue を含む場合があります。サーバーは 24 時間の冪等キャッシュにのみサンプルを保持し、監査記録には保存しません。データコンプライアンス要件に従ってレスポンスとログを取り扱ってください。

レスポンスが PROCESSING の場合、同じ batchId、batchIndex、元のバッチ内容で再試行すると冪等な結果が得られます。バッチ進捗を照会する専用 API はありません。

エラーレスポンス

エラーは 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` バッチ受信後、有効なユーザーが 1 件も一致しませんでした。
400	`55004`	リクエストフィールドまたはリストバッチパラメータが無効です。
503	`55207`	セグメントメタデータが一時的に利用できません。
500	`55000`	内部サーバーエラー。

セグメント作成時、Metadata のビジネスエラーコードと message は呼び出し元に透過されます（例：重複名 40026、上限 40032）。リストアップロードパスでは、「セグメントが存在しない」場合は 40027 ではなく 55201 が返されます。

一致しなかった、または無効なメンバー識別子によってリスト操作全体が失敗することはありません（一致ユーザーが 0 件の OVERRIDE を除く。55214 を参照）。レスポンスは件数と最大 100 件の識別子サンプルを返します。サンプルに identityValue が含まれる場合があるため、レスポンスデータを適切に保護してください。