Program Members

Program Members Endpoint Reference

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 comprised 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’s Members Tab in the Marketo Engage UI.

Describe

The Describe Program Member 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 updatability.

Query

The Get Program Members endpoint allows you to retrieve members of a program.  It requires a programId path parameter, and filterType and 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 “searchableFields” list returned by the Describe Program Member endpoint.  If you specify a filterType that is a custom field, the custom field’s dataType must be either “string” or “integer”.  If you specify a filterType other than “leadId”, a maximum of 100,000 program member records can be processed by the request.  Depending on how your Marketo instance is configured, you will 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 comma-separated format. The call searches for records where the program member’s field matches one of the included filterValues.

The optional fields query parameter accepts a comma separated list of field API names.  When included, each record in the response will include the specified fields.  When omitted, the default set of fields are returned: 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 RFC 7231).  As a workaround, you may change your GET to POST, add _method=GET parameter, and place query string in the request body.

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 “updateable”.  Both endpoints allow you to modify up to 300 program member records per call.

Program Member Status

The Sync Program Member Status 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’s channel.  Valid statuses can be retrieved using the Get Channels endpoint.  If a lead’s current 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 it’s 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 will respond with a status of “updated”, “created”, or “skipped”.   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 “Change Program Status” activity is written to the lead’s activity log.

Program Member Data

The Sync Program Member Data 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 “updateable” (see Describe Program Member 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 will respond with a status of “updated” or “skipped”.   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 “Change Program Member Data” activity is written to the lead’s activity log.

Delete

The Delete Program Members 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 will respond with a status of “deleted” or “skipped”.   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.