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 three 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.
POST /bulk/v1/program/{programId}/members/import.json?format=csv&programMemberStatus=On List
Content-Type: multipart/form-data; boundary=--------------------------118046853683028616211319
Content-Length: 772
Host: <munchkinId>.mktorest.com
----------------------------118046853683028616211319
Content-Disposition: form-data; name="file"; filename="Lead-House-Lannister.csv"
Content-Type: text/csv
firstName,lastName,email,title,company,leadScore
Joanna,Lannister,Joanna@Lannister.com,Lannister,House Lannister,0
Tywin,Lannister,Tywin@Lannister.com,Lannister,House Lannister,0
Cersei,Lannister,Cersei@Lannister.com,Lannister,House Lannister,0
Jamie,Lannister,Jamie@Lannister.com,Lannister,House Lannister,0
Tyrion,Lannister,Tyrion@Lannister.com,Lannister,House Lannister,0
Kevan,Lannister,Kevan@Lannister.com,Lannister,House Lannister,0
Dorna,Lannister,Dorna@Lannister.com,Lannister,House Lannister,0
Lancel,Lannister,Lancel@Lannister.com,Lannister,House Lannister,0
----------------------------118046853683028616211319--
{
"requestId": "17f4a#16f87f87325",
"result": [
{
"batchId": 1040,
"importId": "1040",
"status": "Queued"
}
],
"success": true
}
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 must 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 seven days.
Using the example above, a simple way to call the endpoint is to use cURL from the command line:
curl -i -F format='csv' -F programMemberStatus='On List' -F file='@Lead-House-Lannister.csv' -F access_token='<Access Token>' <REST API Endpoint Base URL>/bulk/v1/program/{programId}/members/import.json
Where the import file “Lead-House-Lannister.csv” contains the following:
firstName,lastName,email,title,company,leadScore
Joanna,Lannister,Joanna@Lannister.com,Lannister,House Lannister,0
Tywin,Lannister,Tywin@Lannister.com,Lannister,House Lannister,0
Cersei,Lannister,Cersei@Lannister.com,Lannister,House Lannister,0
Jamie,Lannister,Jamie@Lannister.com,Lannister,House Lannister,0
Tyrion,Lannister,Tyrion@Lannister.com,Lannister,House Lannister,0
Kevan,Lannister,Kevan@Lannister.com,Lannister,House Lannister,0
Dorna,Lannister,Dorna@Lannister.com,Lannister,House Lannister,0
Lancel,Lannister,Lancel@Lannister.com,Lannister,House Lannister,0
Polling Job Status
Once the import job has been created, you must 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.
GET /bulk/v1/program/members/import/{batchId}/status.json
{
"requestId": "e0cb#16f87f8b177",
"result": [
{
"batchId": 1040,
"importId": "1040",
"status": "Complete",
"numOfLeadsProcessed": 8,
"numOfRowsFailed": 0,
"numOfRowsWithWarning": 0,
"message": "Import succeeded, 8 records imported (8 members)"
}
],
"success": true
}
This response shows a completed import. The status can be one of: Complete, Queued, Importing, Failed.
If the job has completed, you 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.
GET /bulk/v1/program/members/import/{batchId}/failures.json
The endpoint responds 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:
firstName,lastName,email,title,company,leadScore
Aerys,Targaryen,Aerys@Targaryen.com,Targaryen,House Targaryen,TEXT_VALUE_IN_INTEGER_FIELD
When you check the job status, you see numOfRowsFailed is 1 which indicates that a failure occurred:
GET /bulk/v1/program/members/import/{batchId}/status.json
{
"requestId": "4c2d#16f8b32c8ef",
"result": [
{
"batchId": 1046,
"importId": "1046",
"status": "Complete",
"numOfLeadsProcessed": 0,
"numOfRowsFailed": 1,
"numOfRowsWithWarning": 0,
"message": "Import completed with errors, 0 records imported (0 members), 1 failed"
}
],
"success": true
}
Then retrieve the failures file for additional details about the failure:
GET /bulk/v1/program/members/import/{batchId}/failures.json
firstName,lastName,email,title,company,leadScore,Import Failure Reason
Aerys,Targaryen,Aerys@Targaryen.com,Targaryen,House Targaryen,TEXT_VALUE_IN_INTEGER_FIELD,Invalid data type in field Lead Score