Program Members
Marketo exposes APIs for reading, creating, updating, and deleting program member records. Program member records are related to lead records via the lead id field. The records are composed of a set of standard fields, and optionally up to 20 additional custom fields. The fields contain program-specific data for each member, and can be used in forms, filters, triggers, and flow actions. This data is viewable in the program鈥檚 Members Tab in the Marketo Engage UI.
Describe
The endpoint follows the standard pattern for lead database objects. The searchableFields array gives you the set of fields which are valid for querying. The fields array contains field metadata including REST API name, display name, and field update-ability.
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
}
Query
The endpoint allows you to retrieve members of a program. It requires a programId path parameter, and filterType听补苍诲听filterValues query parameters.
programId is used to specify which program to search.
filterType is used to specify which field to use as search filter. It accepts any field in the 鈥渟earchableFields鈥� list returned by the endpoint. If you specify a filterType that is a custom field, the custom field鈥檚 dataType must be either 鈥渟tring鈥� or 鈥渋nteger鈥�. If you specify a filterType other than 鈥渓eadId鈥�, a maximum of 100,000 program member records can be processed by the request. Depending on how your Marketo instance is configured, you receive one of the following errors:
- If the total number of program members exceeds 100,000, an error is returned: 鈥�1003, Total membership size: 100,001 exceeds the limit allowed 100,000 for the filter鈥�.
- If the total number of program members that match the filter exceeds 100,000, an error is returned: 鈥�1003, Matching membership size: 100,001 exceeds the limit allowed (100,000) for this api鈥�.
To query a program whose membership count is exceeds the limit, use the Bulk Program Member Extract API instead.
filterValues is used to specify which values to search for, and accepts up to 300 values in a comma-separated format. The call searches for records where the program member鈥檚 field matches one of the included filterValues.
Alternatively, you can filter by date range by specifying updatedAt as filterType with startAt and endAt datetime parameters. The range must be seven days or fewer. Datetimes should be in an ISO-8601 format, without milliseconds.
The optional fields query parameter accepts a comma-separated list of field API names that returned by the endpoint. When included, each record in the response includes the specified fields. When omitted, the default set of fields returned are acquiredBy, leadId, membershipDate, programId, and reachedSuccess.
By default, a maximum of 300 records are returned. You can use the batchSize query parameter to reduce this number. If the moreResult attribute is true, this means more results are available. Continue to call this endpoint until the moreResult attribute returns false, which means there are no results available. The nextPageToken returned from this API should always be reused for the next iteration of this call.
If the total length of your GET request exceeds 8KB, an HTTP error is returned: 鈥�414, URI too long鈥� (per聽). As a workaround, you may change your GET to POST, add聽_method=GET聽parameter, and place query string in the request body.
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
}
Create and Update
There are two endpoints that support create/update operation on program members. One allows you to update program member status only. The other allows you to update the set of program member fields that are marked as 鈥渦pdateable鈥�. Both endpoints allow you to modify up to 300 program member records per call.
Program Member Status
The endpoint is used to create or update the program status for one or more members.
The required programId path parameter specifies the program containing members to create or update.
The required statusName parameter specifies the program status to apply to a list of leads. The statusName must match an available status for the program鈥檚 channel. Valid statuses can be retrieved using the endpoint. If a lead鈥檚 status has a greater step value than the designated statusName, then that lead will be skipped.
The required input parameter is an array of leadId that correspond to program members. You can submit up to 300 leadIds per call. An upsert operation is performed on each record. If the leadId is associated with a program member, then its membership status is updated. If not, a new program member record is created, the record is associated with the leadId, and the membership status is assigned.
The endpoint responds with a status of 鈥渦pdated鈥�, 鈥渃reated鈥�, or 鈥渟kipped鈥�. If skipped, a reasons array will also be included. The endpoint will also respond with a seq field which is an index that can be used to correlate the submitted records to the order of the response.
If the call is successful, a 鈥淐hange Program Status鈥� activity is written to the lead鈥檚 activity log.
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
}
Program Member Data
The endpoint is used to update program member field data for one or more members. You can modify any custom field, or standard fields that are 鈥渦pdateable鈥� (see endpoint).
The required programId path parameter specifies the program containing members to update.
The required input parameter is an array. Each array element contains a leadId and one or more fields to update (using API name). An update operation is performed on each record. The leadId must be associated with a program member. The fields must be updateable. You can submit up to 300 leadIds per call.
The endpoint responds with a status of 鈥渦pdated鈥� or 鈥渟kipped鈥�. If skipped, a reasons array will also be included. The endpoint will also respond with a seq field which is an index that can be used to correlate the submitted records to the order of the response.
If the call is successful, a 鈥淐hange Program Member Data鈥� activity is written to the lead鈥檚 activity log.
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
}
Fields
The program member object contains standard fields and optional custom fields. Standard fields are present in every Marketo Engage subscription whereas custom fields are created by the user as needed. Each field definition is composed of a set of attributes that describe the field. Examples of attributes are display name, API name, and dataType. These attributes are known collectively as metadata.
The following endpoints allow you to query, create, and update fields on the program member object. These APIs require that the owning API user have a role with one or both of the Read-Write Schema Standard Field 听辞谤听 Read-Write Schema Custom Field 听辫别谤尘颈蝉蝉颈辞苍蝉.
Query Fields
Querying program member fields is straightforward. You may query a single program member field by API name or query the set of all program member fields. Both standard fields and custom fields can be retrieved, depending on the role permissions being used. Hidden fields are also retrieved.
By Name
罢丑别听 endpoint retrieves metadata for a single field on the program member object. The required fieldApiName聽path parameter specifies the API name of the field. The response is like the聽Describe Program Member聽endpoint but contains additional metadata such as the聽isCustom聽attribute which denotes whether the field is a custom field.
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
}
Browse
罢丑别听 endpoint retrieves metadata for all fields on the program member object. By default, a maximum of 300 records are returned. You can use the batchSize聽query parameter to reduce this number. If the聽moreResult聽attribute is true, this means more results are available. Continue to call this endpoint until the moreResult attribute returns false, which means there are no results available. 罢丑别听nextPageToken聽returned from this API should always be reused for the next iteration of this call.
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
}
Create Fields
罢丑别听 endpoint creates one or more custom fields on the program member object. This endpoint provides functionality that is comparable to what is available in the Marketo Engage UI. You can create a maximum of up to 20 custom fields using this endpoint.
Carefully consider each field that you create in your production instance of Marketo Engage using the API. Once a field has been created, you cannot delete it (you can only hide it). Proliferation of unused fields is a bad practice that will add clutter to your instance.
The required聽input parameter is an array of program member field objects. Each object contains one or more attributes. Required attributes are the displayName,听name, and聽dataType聽which correspond to the UI display name of the field, the API name of the field, and the field type respectively. Optionally you may specify聽description,听isHidden,听isHtmlEncodingInEmail,补苍诲听isSensitive.
There are a few rules associated with聽name听补苍诲听displayName聽naming. 罢丑别听name聽attribute must be unique, start with a letter, and only contain letters, numbers, or underscore. 罢丑别听*isplayName聽must be unique, and cannot contain special characters. A common naming convention is to apply聽听迟辞听displayName聽to produce聽name. For example, a聽displayName聽of 鈥淢y Custom Field鈥� would produce a聽name聽of 鈥渕yCustomField鈥�.
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
}
Update Field
罢丑别听 endpoint updates a single custom field on the program member object. Generally, field update operations performed using the Marketo Engage UI are achievable using the API. There are a few differences summarized in the table below.
The required聽fieldApiName聽path parameter specifies the API name of the field to update. The required聽input聽parameter is an array that contains a single lead field object. The field object contains one or more attributes.
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
}
Delete
The endpoint is used to delete program member records. The required programId path parameter specifies the program containing members to delete. The request body contains an input array of lead ids. A maximum of 300 lead ids聽 per call are permitted.
The endpoint responds with a status of 鈥渄eleted鈥� or 鈥渟kipped鈥�. If skipped, a reasons array will also be included. The endpoint will also respond with a seq field which is an index that can be used to correlate the submitted records to the order of the response.
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
}