Bulk Program Member Import

Bulk Program Member Import Endpoint Reference

For large amounts of program member records, program members can be imported asynchronously with the bulk API.  This allows you to import a list of records into Marketo using a flat file with the delimiters (comma, tab, or semi-colon).  The file can contain any number of records, so long as the file totals less than 10MB in size.  The record operation is “insert or update” only.

Processing Limits

You are allowed to submit more than one bulk import request, with limitations.  Each request is added as a job to a FIFO queue to be processed.  A maximum of 2 jobs are processed at the same time.  A maximum of 10 jobs are allowed in the queue at any given time (including the 2 currently being processed).  If you exceed the 10 job maximum, then a “1016, Too many imports” error is returned.

Import File

The first row of the file must be a header which lists the corresponding REST API names as fields to map the values of each row into.  REST API names can be retrieved using Describe Lead and/or Describe Program Member endpoints.  Records can contain lead fields, custom lead fields, and custom program member fields.

A typical file would follow this basic pattern:

The call itself is made using the multipart/form-data content-type.
This request type can be difficult to implement, so it is highly recommended that you use an existing library implementation.

Creating a Job

The Import Program Members endpoint reads a file containing program member records and adds them to a program with a given status.  The records can contain both lead fields and program member custom fields.  All records must include the email field, which is used for deduplication purposes.

The programId path parameter specifies the program to which the members are added.

There are 3 required query parameters.  The format parameter specifies the import file format (CSV, TSV, or SSV), the programMemberStatus parameter specifies the program status for the members that are being added to the program, and the file parameter contains the name of the import file that contains program member records.

Notice in the response to our call that there is a batchId and a status field for the record in the result array.  Since this endpoint is asynchronous, it can return a status of Queued, Importing, or Failed.  You will need to retain the batchId to get the status of the import job, and to retrieve failures and/or warnings upon completion.   The batchId remains valid for 7 days.

Using the example above, a simple way to call the endpoint is to use cURL from the command line:

Where the import file “Lead-House-Lannister.csv” contains the following:

Polling Job Status

Once the import job has been created, you need to query its status.  It is best practice to poll the import job every 5-30 seconds.  Do this by passing the batchId path parameter to the Get Import Program Member Status endpoint.

This response shows a completed import.  The status can be one of: Complete, Queued, Importing, Failed.

If the job has completed, you’ll have a listing of the number of rows processed, failed, or with warnings.  The message parameter may also give the failure message if status is Failed.

Failures

Failures are indicated by the numOfRowsFailed attribute in Get Import Program Member Status response.  If numOfRowsFailed is greater than zero, then that value indicates the number of failures that occurred.

Use the Get Import Program Member Failures endpoint to retrieve records and causes of failed rows by passing the batchId path parameter.

The endpoint will respond with a file indicating which rows failed, along with a message indicating why the record failed.  The format of the file is the same as specified in format parameter during job creation.  An additional field is appended to each record with a description of the failure.

For example, suppose that you import the following file with an invalid lead score:

When you check the job status you see “numOfRowsFailed” is  1 which indicates that a failure occurred:

You then retrieve the failures file for additional detail about the failure:

Warnings

Warnings are indicated by the numOfRowsWithWarning attribute in Get Import Program Member Status response.  If numOfRowsWithWarning is greater than zero, then that value indicates the number of warnings that occurred.

Use the Get Import Program Member Warnings endpoint to retrieve records and causes of warning rows by passing the batchId path parameter.

The endpoint will respond with a file indicating which rows produced warnings, along with a message indicating why the record produced a warning.  The format of the file is the same as specified in format parameter during job creation.  An additional field is appended to each record with a description of the warning.

For example, suppose that you import the following file with an invalid email address:

When you check the job status you see  numOfRowsWithWarning is  1 which indicates that a warning occurred:

You then retrieve the warnings file for additional detail about the warning: