Bulk Import

Bulk Import provides interfaces for inserting large sets of person and person-related data. You can import three object types:

To perform a bulk import, create a job that reads an uploaded file. The job runs asynchronously, so poll it to retrieve the import status.

Upload files using HTTP multipart/form-data per RFC 2399.

Unlike other endpoints, Bulk API endpoints are not prefixed with /rest.

Authentication

The bulk import APIs use the same OAuth 2.0 authentication method as other Marketo REST APIs. Send a valid access token in the Authorization: Bearer {_AccessToken_} HTTP header.

Limits

Permissions

Bulk Import uses the same permissions model as the Marketo REST API. It does not require additional permissions, but each set of endpoints requires specific permissions.

Record Operations

Bulk import is an “insert or update” record operation. If the database contains a matching record, the operation updates it. Otherwise, the operation creates a record.

The bulk import response does not indicate whether an individual record was updated or inserted.

Creating a Job

Create a lead import job by calling the Import Leads endpoint. This endpoint uses multipart/form-data as the content-type.

Use an HTTP support library for your preferred language to construct the multipart request. You can also use curl to get started.

POST /bulk/v1/leads.json?format=csv

Content-Type: multipart/form-data; boundary=--------------------------WebKitFormBoundaryBQACkJZyaiIAXogC
Content-Length: 311
Host: <munchkinId>.mktorest.com

------WebKitFormBoundaryBQACkJZyaiIAXogC
Content-Disposition: form-data; name="file"; filename="leads.csv"
Content-Type: text/csv

firstName,lastName,email
Able,Baker,ablebaker@marketo.com
Charlie,Dog,charliedog@marketo.com
Easy,Fox,easyfox@marketo.com
------WebKitFormBoundaryBQACkJZyaiIAXogC--

This request creates a job that imports values from the CSV file named leads.csv.

{
    "requestId": "d01f#15d672f8560",
    "result": [
        {
            "batchId": 3404,
            "importId": "3404",
            "status": "Queued"
        }
    ],
    "success": true
}

The response returns a batchId. Use this value to check the job status.

Common Parameters

Each job creation endpoint shares parameters for configuring the import file. An import subtype can also support additional parameters.

Polling Job Status

Pass the batchId to the Get Import Lead Status endpoint to retrieve the job status.

GET /bulk/v1/leads/batch/{batchId}.json

{
    "requestId": "1f63#15d6738fd15",
    "result": [
        {
            "batchId": 3404,
            "importId": "3404",
            "status": "Complete",
            "numOfLeadsProcessed": 3,
            "numOfRowsFailed": 0,
            "numOfRowsWithWarning": 0,
            "message": "Import succeeded, 3 records imported (3 members)"
        }
    ],
    "success": true
}

The status member indicates the job’s progress. Its value can be Queued, Importing, Complete, or Failed.

In this example, the job is complete, so polling can stop.

Failures

The numOfRowsFailed attribute in the Get Import Lead Status response indicates the number of failed rows. A value greater than zero means that failures occurred.

To retrieve the failed records and their causes, use the Get Import Lead Failures endpoint.

GET /bulk/v1/leads/batch/{batchId}/failures.json

The failure file identifies each failed row and explains why the record failed.