Learn about the V5 Contact Bulk Import
Q. Does this endpoint support webhook or callback URL notifications?
A. No. notify_callback only accepts a list of email addresses. Webhook callbacks are not supported on this endpoint. This differs from the older apiv2 bulk upload API, which supports both an email and a callback URL.
Q. Does the response to my request confirm the import succeeded?
A. No. A 200 response only confirms the request was accepted for processing. The import itself runs in the background, and the result is reported later by email to each address in notify_callback.
Q. What happens if my file is missing a column the system expects?
A. This is reported immediately in the request response, not in the later email. The response's data array lists each missing attribute by name, along with the file name and extension, so you can fix the file before the import proceeds.
Q. Does Total Records in the notification email include the header row?
A. Yes. Total Records is the row count of the file as uploaded, including the header row, not the number of contact records alone.
Q. If one record in my file fails, does the rest still get processed?
A. Yes. Processing continues for the remaining records. For example, in a 10 row file (including header) where row 6 fails, the other 9 rows are still imported; only row 6 is excluded.
Q. Will I be told which specific records failed and why?
A. Not inline in the email body. Every notification gives aggregate counts and, where relevant, a general cause. When one or more records failed, the email also includes a direct download link to the specific records that couldn't be uploaded.
Q. What's the difference between the three notification emails?
- Upload Failed: the entire request could not be processed (for example, no valid primary key column). States a Reason, no Successful Upload or Failed Records count.
- Upload Successful: every data row in the file was processed without error. States Total Records and Successful Upload; Successful Upload is exactly Total Records minus the header row.
- Upload Partial Success: the request completed but one or more records failed. States Total Records, Successful Upload, and Failed Records, plus a general cause and a download link to the failed records.
Q. What file formats does the file accept, and is there a size limit?
A. .csv or a .zip that contains a CSV, uploaded as binary content in the multipart request. A public URL input and a maximum size (reportedly under 3 GB) were raised in an engineering discussion, but neither appears in the current API spec for this endpoint; treat both as unconfirmed until engineering verifies them against this endpoint specifically.
Q. Can I save an import without processing it right away?
A. Yes. Set import_state to draft to save without processing, or publish to process it immediately.
Q. What's the difference between anonymous and identified contact_type, and why do I need to set it?
A. Identified contacts have a primary key value, such as email or mobile number. Anonymous contacts are ones for which the primary key attribute is not available or does not exist in the system. contact_type is required so the API knows which the file contains.
Q. Can more than one person receive the completion email?
A. Yes. notify_callback takes an array of email addresses under email.
Q. What authentication does this endpoint need?
A. An API key header, obtained from the CE panel.
