Bulk Program Member Extract

Bulk Program Member Extract Endpoint Reference

The Bulk Program Member Extract set of REST APIs provides a programmatic interface for retrieving large sets of program member records out of Marketo.  This the recommended interface for use cases which require continuous interchange of data between Marketo and one or more external systems, for ETL, data warehousing, and archival purposes.

Permissions

The Bulk Program Member Extract APIs require that the owning API user have a role with one or both of the Read-Only Lead, or Read-Write Lead permissions.

Filters

Program member extract supports filtering by Program Id.

Filter Type Data Type Notes
programId Integer Accepts the id of a program. Jobs will return all accessible records which are members of the program at the time that the job begins processing.

Retrieve program ids using the Get Programs endpoint.

Options

The Create Export Program Member Job endpoint provides several formatting options.  These options give the user the ability to:

  • Specify the fields to include within the exported file
  • Rename column headers of these fields
  • Specify the format of the exported file
Parameter Data Type Required Notes
fields Array[String] Yes The fields parameter accepts a JSON array of strings.   The listed fields will be included in the exported file.

The following field types can be exported:

  • Lead
  • Custom Lead
  • Program Member
  • Custom Program Member

With the exception of program member fields, specify a field using it’s REST API Name.  For program member fields, specify the field using it’s Friendly Name.

The following is a comprehensive list of program member field Friendly Names (actual list varies by subscription):

  • Acquired By
  • Attendance Likelihood
  • Cadence
  • Exhausted
  • Lead Id
  • Member Date
  • Nurture Program Id
  • Program
  • Program Id
  • Program Type Id
  • Recommended
  • Registration Code
  • Registration Likelihood
  • Status
  • Status Id
  • Status Reason
  • Success
  • Track
  • Track Name
  • Waitlist Priority
  • Webinar Url
columnHeaderNames Object  No A JSON object containing key-value pairs of field and column header names.  The key must be the name of a field included in the export job.  The value will be the name of the exported column header for that field.
 format String No Accepts one of: CSV, TSV, SSV.  The exported file will be rendered as a comma-separated values, tab-separated values, or semi-colon separated values file, respectively if set.  Defaults to CSV if unset.

Creating a Job

The parameters for the job are defined before kicking off the export using the Create Export Program Member Job endpoint.  We need to define the filter containing the program id, and the fields that are needed for export.  Optionally we can define the format of the file, and the columnHeaderNames.

This returns a status response indicating that the job has been created.  The job has been defined and created, but it hasn’t yet been kicked off.  To do so, the Enqueue Export Program Member Job endpoint must be called using the exportId from the creation status response:

This will respond with an initial status of “Queued” after which it will be set to “Processing” when there is an available export slot.

Polling Job Status

Note: Status can only be retrieved for jobs which were created by the same API user.

Since this is an asynchronous endpoint, after creating the job we need to poll its status to determine its progress.  Poll using the Get Export Program Member Job Status endpoint.  The status is only updated once every 60 seconds, so a polling frequency lower than this is not advised, and in nearly all cases is still excessive.  The status field may respond with any one of: Created, Queued, Processing, Cancelled, Completed, Failed.

Let’s take a quick look at polling.

The status endpoint responds indicating that the job is still processing, so the file is not yet available for retrieval.  Once the job status changes to “Completed” it will be available for download.

Retrieving Your Data

To retrieve the file of a completed program member export, simply call the Get Export Program Member File endpoint with your exportId.

The response will contain a file formatted in the way that the job was configured.  The endpoint will respond with the contents of the file.  If a requested program member field is empty (contains no data), then null will be placed in the corresponding field in the export file.

To support partial and resumption-friendly retrieval of extracted data, the file endpoint optionally supports the HTTP header Range of the type bytes.  If the header is not set, the whole of the contents will be returned.  You can read more about using the Range header with Marketo Bulk Extract files here.

Cancelling a Job

If a job was configured incorrectly, or becomes unnecessary, it can be easily cancelled using the Cancel Export Program Member Job endpoint:

This will respond with a status indicating that the job has been cancelled.