Create Multiple Records in Marketing Cloud Growth Using Bulk API 2.0

Creating records using Bulk API 2.0 involves a few distinct steps. First, organize your data in a CSV file. Next, send a POST request to create a bulk ingestion job, which provides you with a job ID. Use the job ID to send a PUT request that contains your CSV data. When you finish uploading data, send a PATCH request to change the status of the job and begin processing records.

You can use Bulk API 2.0 to create the record types shown in this table.

Record Type	API Name
Contact records	`Contact`
Campaigns	`Campaign`

Before you send any requests to Bulk API 2.0, obtain a bearer token. For more information, see Connect to REST-based APIs.

Use target field names as the column headers in your CSV file. To retrieve a list of field names, issue a GET call to the /services/data/v61.0/sobjects/OBJECT_API_NAME/describe endpoint, where OBJECT_API_NAME is the API name of the object to describe. Alternatively, you can view a list of fields in the Object Explorer on the Setup page of the Salesforce web app.

There are several other considerations to keep in mind when you create the CSV file. For more information, see Prepare CSV Files in the Bulk API 2.0 and Bulk API Developer Guide.

To begin importing records in bulk, create a bulk ingestion job. Issue a POST request to the /services/data/v61.0/jobs/ingest endpoint. The body of the request must contain at least two properties: object and operation. The value of the object property must match the API name of the record type that you’re inserting.

Set the value of the operation to one of these values:

insert—Use this value to create records.
update—Use this value to update records.
upsert—Use this value to update records when a match is found, or create records when no match is found.

This example shows a request to create a job that ingests contacts in bulk. For additional information and code examples, see createBulkContactIngestionJob.

If the request is successful, the response includes an id value. This value is the job ID, which you use in subsequent operations.

To upload data, send a PUT request to the /services/data/v61.0/jobs/ingest/JOB_ID/batches endpoint, where JOB_ID is your ingestion job ID. Include your data in CSV format in the body of your request. For best results, limit the size of the data to 100 MB. For more information and code examples, see uploadContactData.

For general considerations related to uploading data using Bulk API 2.0, see Upload Job Data in the Bulk API 2.0 and Bulk API Developer Guide.

Change the status of the job to UploadComplete. This step tells the system to start processing the uploaded data. You can change the status by sending a PATCH request to the /services/data/v61.0/jobs/ingest/{jobId} endpoint. The body of the request must be a JSON object with a single property named state with a value of uploadComplete.

To end an ingestion job without processing any records, change the value of state to aborted.

For more information and code examples, see closeBulkContactIngestionJob.

Check the status of the ingestion job by sending a GET request to the /services/data/v61.0/jobs/ingest/JOB_ID endpoint, where JOB_ID is the job ID for the ingestion job. If the request is successful, the response includes a status property, which describes the current state of the job. For more information about retrieving the status of a job, see getBulkContactIngestionJob.

You can also retrieve lists of records that were successfully ingested, that failed to be ingested, or that haven’t been ingested yet.