プログラムメンバー
Marketoには、プログラムメンバーレコードの読み取り、作成、更新、削除用のAPIが用意されています。 「リード ID」フィールドは、プログラムメンバーのレコードとリードレコードを関連付けます。
各レコードには標準フィールドが含まれ、最大20個のカスタムフィールドを含めることができます。 これらのフィールドには、フォーム、フィルター、トリガー、フローアクションで使用するためのプログラム固有のメンバーデータが保存されます。 このデータは、Marketo Engage UIのプログラムの メンバー タブで確認できます。
説明
プログラム メンバーの説明 エンドポイントは、リード データベース オブジェクトの標準パターンに従います。
searchableFields配列は、クエリに有効なフィールドを識別します。fields配列には、REST API名、表示名、フィールドが更新可能かどうかなどのメタデータが含まれています。
GET /rest/v1/programs/members/describe.json
{
"requestId": "f813#1791563c7cc",
"result": [
{
"name": "API Program Membership",
"description": "Map for API program membership fields",
"createdAt": "2021-03-20T01:30:05Z",
"updatedAt": "2021-03-20T01:30:05Z",
"dedupeFields": [
"leadId",
"programId"
],
"searchableFields": [
[
"leadId"
],
[
"myCustomField"
],
[
"reachedSuccess"
],
[
"statusName"
]
],
"fields": [
{
"name": "acquiredBy",
"displayName": "acquiredBy",
"dataType": "boolean",
"updateable": false,
"crmManaged": false
},
{
"name": "attendanceLikelihood",
"displayName": "attendanceLikelihood",
"dataType": "integer",
"updateable": false,
"crmManaged": false
},
{
"name": "createdAt",
"displayName": "createdAt",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "isExhausted",
"displayName": "isExhausted",
"dataType": "boolean",
"updateable": false,
"crmManaged": false
},
{
"name": "leadId",
"displayName": "leadId",
"dataType": "integer",
"updateable": false,
"crmManaged": false
},
{
"name": "membershipDate",
"displayName": "membershipDate",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "nurtureCadence",
"displayName": "nurtureCadence",
"dataType": "string",
"length": 4,
"updateable": false,
"crmManaged": false
},
{
"name": "program",
"displayName": "program",
"dataType": "string",
"length": 255,
"updateable": false,
"crmManaged": false
},
{
"name": "programId",
"displayName": "programId",
"dataType": "integer",
"updateable": false,
"crmManaged": false
},
{
"name": "reachedSuccess",
"displayName": "reachedSuccess",
"dataType": "boolean",
"updateable": false,
"crmManaged": false
},
{
"name": "reachedSuccessDate",
"displayName": "reachedSuccessDate",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "registrationLikelihood",
"displayName": "registrationLikelihood",
"dataType": "integer",
"updateable": false,
"crmManaged": false
},
{
"name": "statusName",
"displayName": "statusName",
"dataType": "string",
"length": 255,
"updateable": false,
"crmManaged": false
},
{
"name": "statusReason",
"displayName": "statusReason",
"dataType": "string",
"length": 255,
"updateable": false,
"crmManaged": false
},
{
"name": "trackName",
"displayName": "trackName",
"dataType": "string",
"length": 255,
"updateable": false,
"crmManaged": false
},
{
"name": "updatedAt",
"displayName": "updatedAt",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "waitlistPriority",
"displayName": "waitlistPriority",
"dataType": "integer",
"updateable": false,
"crmManaged": false
},
{
"name": "myCustomField",
"displayName": "myCustomField",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "registrationCode",
"displayName": "registrationCode",
"dataType": "string",
"length": 100,
"updateable": true,
"crmManaged": false
},
{
"name": "webinarUrl",
"displayName": "webinarUrl",
"dataType": "string",
"length": 2000,
"updateable": true,
"crmManaged": false
}
]
}
],
"success": true
}
クエリ
プログラムのメンバーを取得するには、 プログラムメンバーを取得 エンドポイントを使用します。 リクエストには、programId パスパラメーターとfilterTypeおよびfilterValues クエリパラメーターが必要です。
programIdは、検索するプログラムを指定します。
filterTypeは、検索フィルターとして使用するフィールドを指定します。 プログラムメンバーを説明エンドポイントから返される “searchableFields” リスト内の任意のフィールドを受け取ります。 カスタムフィールドの場合、dataTypeは「文字列」または「整数」である必要があります。
filterTypeが「leadId」でない場合、リクエストは最大100,000件のプログラムメンバーレコードを処理できます。 Marketo インスタンス設定に応じて、次のいずれかのエラーが発生します。
- プログラムメンバーの合計数が 100,000 を超えると、「1003、合計メンバーシップサイズ：100,001 は、フィルターで許可されている制限の 100,000 を超えています」というエラーが返されます。
- フィルターに一致するプログラムメンバーの合計数が 100,000 を超えると、「1003、一致するメンバーシップサイズ：100,001 は、この API で許可されている制限（100,000）を超えています」というエラーが返されます。
メンバーシップ数が制限を超えているプログラムをクエリするには、代わりにBulk Program Member Extract APIを使用します。
filterValuesは、検索する値を指定し、最大300個のコンマ区切りの値を受け入れます。 呼び出しは、プログラムメンバーフィールドが含まれているfilterValueのいずれかに一致するレコードを検索します。
または、updatedAtをfilterTypeとして指定し、startAtとendAtの日時パラメーターを指定して、日付範囲でフィルタリングします。 範囲は 7日以内にする必要があります。 日時の値にミリ秒以外のISO-8601形式を使用します。
オプションのfields クエリパラメーターは、 プログラムメンバー エンドポイントによって返されるフィールド API名のコンマ区切りリストを受け入れます。 含まれている場合、各応答レコードには指定されたフィールドが含まれます。 省略すると、デフォルトでacquiredBy、leadId、membershipDate、programIdおよびreachedSuccessが返されます。
デフォルトでは、エンドポイントは最大300件のレコードを返します。 この数を減らすには、batchSize クエリパラメーターを使用します。
moreResult属性がtrueの場合、より多くの結果を使用できます。 返されたnextPageTokenでエンドポイントの呼び出しを続行し、moreResultがfalseになるまで呼び出します。
GET リクエストの合計長が8 KBを超えた場合、エンドポイントはHTTP エラー「414、URIが長すぎます」を返します。 この制限を回避するには、リクエストをGETからPOSTに変更し、_method=GET パラメーターを追加して、クエリ文字列をリクエスト本文に配置します。
GET /rest/v1/programs/{programId}/members.json?filterType=statusName&filterValues=Influenced
{
"requestId": "109da#17915eec072",
"result": [
{
"seq": 0,
"leadId": 1789,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 1,
"leadId": 1790,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 2,
"leadId": 1791,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 3,
"leadId": 1792,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 4,
"leadId": 1793,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 5,
"leadId": 1794,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 6,
"leadId": 1795,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 7,
"leadId": 1796,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 8,
"leadId": 1797,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 9,
"leadId": 1798,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 10,
"leadId": 1799,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
},
{
"seq": 11,
"leadId": 1800,
"reachedSuccess": true,
"programId": 1044,
"acquiredBy": true,
"membershipDate": "2020-01-08T18:10:26Z"
}
],
"success": true,
"moreResult": false
}
作成と更新
プログラムメンバーに対する作成と更新の操作をサポートする2つのエンドポイント：
- 1つのエンドポイントは、プログラムメンバーのステータスのみを更新します。
- 1つのエンドポイントは、「更新可能」としてマークされたプログラムメンバーフィールドを更新します。
各エンドポイントは、1回の呼び出しごとに最大300件のプログラムメンバーレコードを変更できます。
プログラムメンバーステータス
プログラムメンバーステータスの同期 エンドポイントを使用して、1人以上のメンバーのプログラムステータスを作成または更新します。
必要なパラメーターは次のとおりです。
programId：作成または更新するメンバーを含むプログラムを指定するパスパラメーター。statusName: リードのリストに適用するプログラムのステータスを指定します。 statusName は、プログラムのチャネルで使用可能なステータスと一致する必要があります。 チャネルを取得 エンドポイントを使用して有効なステータスを取得します。 リードのステータスが、指定されたstatusNameよりも大きいステップ値を持つ場合、リクエストはそのリードをスキップします。input: プログラムメンバーに対応するleadId値の配列。 呼び出しごとに、最大 300 個のリード ID を送信できます。
エンドポイントは、各レコードに対してアップサートを実行します。 leadIdがプログラムメンバーに関連付けられている場合、エンドポイントはそのメンバーシップステータスを更新します。 そうでない場合は、プログラムメンバーレコードを作成し、レコードをleadIdに関連付け、メンバーシップステータスを割り当てます。
応答には、「更新済み」、「作成済み」、または「スキップ済み」のstatusが含まれます。 スキップされた結果には、reasons配列も含まれます。 seq フィールドは、送信された各レコードと応答順序を関連付けるインデックスです。
呼び出しが成功すると、「プログラムステータスを変更」アクティビティがリードのアクティビティログに書き込まれます。
POST /rest/v1/programs/{programId}/members/status.json
Content-Type: application/json
{
"statusName":"Influenced",
"input":[
{
"leadId": 1800
},
{
"leadId": 1801
},
{
"leadId": 1235
}
]
}
{
"requestId": "14b2d#17916378ec5",
"result": [
{
"seq": 0,
"status": "skipped",
"reasons": [
{
"code": "1037",
"message": "Lead skipped because it is already in or past this status"
}
]
},
{
"seq": 1,
"status": "updated",
"leadId": 1801
},
{
"seq": 2,
"status": "created",
"leadId": 1235
}
],
"success": true
}
プログラムメンバーデータ
プログラムメンバーデータの同期 エンドポイントを使用して、1人以上のメンバーのプログラムメンバーフィールドデータを更新します。 プログラム メンバーの説明 エンドポイントによって「更新可能」とマークされた任意のカスタム フィールドまたは任意の標準フィールドを変更できます。
必要なパラメーターは次のとおりです。
programId：更新するメンバーを含むプログラムを指定するパスパラメーター。input: API名で更新するleadIdと1つ以上のフィールドを要素に含む配列。 呼び出しごとに、最大 300 個のリード ID を送信できます。
エンドポイントは、各レコードを更新します。 leadIdはプログラムメンバーに関連付ける必要があり、各フィールドは更新可能である必要があります。
応答には、「更新」または「スキップ」のstatusが含まれます。 スキップされた結果には、reasons配列も含まれます。 seq フィールドは、送信された各レコードと応答順序を関連付けるインデックスです。
呼び出しが成功すると、「プログラムメンバーデータを変更」アクティビティがリードのアクティビティログに書き込まれます。
POST /rest/v1/programs/{programId}/members.json
Content-Type: application/json
{
"input":[
{
"leadId": 1789,
"registrationCode": "dcff5f12-a7c7-11eb-bcbc-0242ac130002"
},
{
"leadId": 1790,
"registrationCode": "c0404b78-d3fd-47bf-82c4-d16f3852ab3a"
},
{
"leadId": 1003,
"registrationCode": "aa880c57-75b8-426b-a33a-fbf6302d7cb4"
}
]
}
{
"requestId": "edc3#1791659b8d2",
"result": [
{
"seq": 0,
"status": "updated",
"leadId": 1789
},
{
"seq": 1,
"status": "updated",
"leadId": 1790
},
{
"seq": 2,
"status": "skipped",
"reasons": [
{
"code": "1013",
"message": "Membership not found"
}
]
}
],
"success": true
}
フィールド
プログラムメンバーオブジェクトには、標準フィールドとオプションのカスタムフィールドが含まれます。 標準フィールドはMarketo Engageのサブスクリプションごとに用意されていますが、カスタムフィールドは必要に応じて作成できます。
各フィールドは、表示名、API名、dataTypeなどの属性で定義されます。 これらの属性をメタデータと呼びます。
次のエンドポイントは、プログラムメンバーオブジェクトのフィールドのクエリ、作成、更新を行います。 API ユーザーには、読み取り/書き込みスキーマ標準フィールド権限、読み取り/書き込みスキーマカスタムフィールド権限、またはその両方を持つ役割が必要です。
クエリフィールド
API名で1つのプログラムメンバーフィールドをクエリするか、すべてのプログラムメンバーフィールドを取得します。 役割の権限は、応答に標準フィールド、カスタムフィールド、またはその両方を含めることができるかどうかを決定します。 応答には非表示のフィールドも含まれます。
名前別
名前でプログラムメンバーフィールドを取得 エンドポイントは、プログラムメンバーオブジェクトの1つのフィールドのメタデータを取得します。 必須のfieldApiName パスパラメーターは、フィールドのAPI名を指定します。
応答はプログラムメンバーの説明の応答に似ていますが、追加のメタデータが含まれています。 例えば、isCustom属性は、フィールドがカスタムかどうかを示します。
GET /rest/v1/programs/members/schema/fields/{fieldApiName}.json
{
"requestId": "15416#17e955554de",
"result": [
{
"displayName": "Status",
"name": "statusName",
"description": null,
"dataType": "string",
"length": 255,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
}
],
"success": true
}
参照
プログラムメンバーフィールドを取得エンドポイントは、プログラムメンバーオブジェクトのすべてのフィールドのメタデータを取得します。 デフォルトでは、最大300件のレコードが返されます。 この数を減らすには、batchSize クエリパラメーターを使用します。
moreResult 属性が true の場合、さらに多くの結果が使用可能です。 返されたnextPageTokenでエンドポイントの呼び出しを続行し、moreResultがfalseになるまで呼び出します。
GET /rest/v1/programs/members/schema/fields.json?batchSize=5
{
"requestId": "102f6#17e9557f123",
"result": [
{
"displayName": "Acquired By",
"name": "acquiredBy",
"description": null,
"dataType": "boolean",
"isHidden": false,
"isHtmlEncodingInEmail": false,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Nurture Cadence",
"name": "nurtureCadence",
"description": null,
"dataType": "string",
"length": 4,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Nurture Exhausted",
"name": "isExhausted",
"description": null,
"dataType": "boolean",
"isHidden": false,
"isHtmlEncodingInEmail": false,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Member Date",
"name": "membershipDate",
"description": null,
"dataType": "datetime",
"isHidden": false,
"isHtmlEncodingInEmail": false,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Program",
"name": "program",
"description": null,
"dataType": "string",
"length": 255,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
}
],
"success": true,
"nextPageToken": "BC7J6EPVLT6T4B5FKUU3APCYN4======",
"moreResult": true
}
フィールドの作成
プログラムメンバーフィールドの作成 エンドポイントは、プログラムメンバーオブジェクトにカスタムフィールドを作成します。 Marketo Engage UIと同等の機能を提供します。 このエンドポイントを使用して、最大20個のカスタムフィールドを作成できます。
実稼動Marketo Engage インスタンスで作成する前に、各フィールドを慎重に検討します。 フィールドを作成した後は、削除できません。非表示にできるのはのみです。 未使用のフィールドは、インスタンスを混乱させます。
必須の input パラメーターは、プログラムメンバーフィールドオブジェクトの配列です。 各オブジェクトには、1 つ以上の属性が含まれます。
- 必要な属性は
displayName、name、dataTypeです。 UIの表示名、API名、フィールドタイプにそれぞれ対応します。 - オプションの属性は
description、isHidden、isHtmlEncodingInEmail、およびisSensitiveです。
nameおよびdisplayName属性には、次の命名ルールがあります。
name属性は一意で、文字で始まり、文字、数字、アンダースコアのみを含める必要があります。- *
isplayNameは一意である必要があり、特殊文字を含めることはできません。
一般的な規則は、 キャメルケース をdisplayNameに適用してnameを生成することです。 例えば、「My Custom Field」のdisplayNameは、「myCustomField」のnameを生成します。
POST /rest/v1/programs/members/schema/fields.json
{
"input": [
{
"displayName": "PMCF Custom Field 03",
"name": "pMCFCustomField03",
"description": "My third custom field",
"dataType": "string"
}
]
}
{
"requestId": "13a7#17e955fcb44",
"result": [
{
"name": "pMCFCustomField03",
"status": "created"
}
],
"success": true
}
フィールドの更新
プログラムメンバーフィールドの更新 エンドポイントは、プログラムメンバーオブジェクトの1つのカスタムフィールドを更新します。 Marketo Engage UIで利用できるフィールドの更新のほとんどは、APIからも利用できます。 次の表に、その違いをまとめました。
リクエストには次のパラメーターが必要です。
fieldApiName：更新するフィールドのAPI名を指定するパスパラメーター。input: 1つ以上の属性を持つ1つのリードフィールドオブジェクトを含む配列。
POST /rest/v1/programs/members/schema/fields/pMCFCustomField03.json
{
"input": [
{
"displayName": "Lunch Preference",
"description": "Attendee food preference",
"isHtmlEncodingInEmail": true
}
]
}
{
"requestId": "215f#17e95663955",
"result": [
{
"name": "pMCFCustomField03",
"status": "updated"
}
],
"success": true
}
削除
プログラムメンバーレコードを削除するには、 プログラムメンバーの削除 エンドポイントを使用します。 必須のprogramId パス パラメーターは、削除するメンバーを含むプログラムを指定します。
リクエスト本文には、リード IDのinput配列が含まれています。 各呼び出しでは、最大300個のリード IDを使用できます。
応答には、「削除済み」または「スキップ済み」のstatusが含まれています。 スキップされた結果には、reasons配列も含まれます。 seq フィールドは、送信された各レコードと応答順序を関連付けるインデックスです。
POST /rest/v1/programs/{programId}/members/delete.json
Content-Type: application/json
{
"input":[
{
"leadId": 1235
},
{
"leadId": 77
}
]
}
{
"requestId": "302a#17916619417",
"result": [
{
"seq": 0,
"status": "deleted",
"leadId": 1235
},
{
"seq": 1,
"status": "skipped",
"reasons": [
{
"code": "1037",
"message": "Lead not in program"
}
]
}
],
"success": true
}