Bulk Write APIs - An Overview
Bulk Write API allows you to insert, update, or upsert a large set of data. This is an asynchronous API, meaning that the response of your request is not available immediately. When the records are processed, the system notifies you of job completion in the callback URL or you can check the job status periodically.
This API allows you to insert, update, or upsert a maximum of 25000 records in a single API call.
How it Works
Step 1: Prepare your CSV file
The Bulk Write API accepts only CSV file compressed into a ZIP file.
The first row in the CSV file should be the field API names. Each subsequent row corresponds to a record in Bigin. A CSV file can contain multiple records. All the records in the CSV file must be for the same module. Below is a sample CSV file for inserting records in Contacts module.
Refer to Limitations to know about CSV file limits.
Step 2: Upload your file
Upload your CSV file with the required data as a compressed zip file. The response contains the file_id. Use this ID while making a bulk write request.
Refer to Upload File to know how to upload the CSV file.
Step 3: Create a bulk write job
Create(or make) a POST API call with the file_id(from the Upload API), callback URL, operation type (insert, update, or upsert), the module and related fields, and their field mappings. It will create an asynchronous job and return an 'ID', which is the reference for your request.
Refer to Create Bulk Write Job for more details.
Step 4: Check job status
The system notifies you of job completion in the specified 'callback URL'. To check the status of the job before its completion, make a GET API call with the ‘ID’ of the job.
Refer Get Bulk Write Job Details to know more.
Step 5 : Download the result
On successful job completion, the 'download_url' is available in the 'result' attribute of the job details. Call the 'download_url' to download the result. The downloaded file will be in CSV format within a ZIP file and will contain the first three mapped columns from the uploaded file, and three more columns — ID, Status, and Error.
Refer to Download Result for more details.