Importing contacts from a CSV file
An audience is filled from a CSV file in four calls: open an import with its consent block and the column mapping, upload the file to the address the answer gives, start the import, and read its progress until it ends. The file never passes through the API: it goes straight to storage through a presigned upload, and the platform's contact store keeps every address (as a hash and an encrypted copy). Broadcasts keeps the counts, the consent facts and the failed row numbers, never a cell value.
Consent comes first
Broadcasts sends to permission-based lists only. Every import carries a consent block, and a request without one is refused before anything is stored: the request schema answers 400 with the validation problem and the path consent. The block names where the consent was collected and when:
{
"consent": { "source": "signup form", "collected_at": "2026-09-01T00:00:00.000Z" },
"mapping": { "email": "Email", "fields": { "first_name": "First name", "plan": "Plan" } },
"size_bytes": 48213
}consent.sourceis a label of 1 to 64 characters: no@and no control characters, because it is stored next to every imported contact and must never hold an address.consent.collected_atis an instant; one more than five minutes in the future is refused (422).- Every contact of the file gets this consent record. A broadcast whose resolved recipients have no consent record at all is blocked by the checklist (
no_consent) and cannot be approved.
The calls
| Step | Route | What it does |
|---|---|---|
| Open | POST /v1/audiences/{audience_id}/imports (broadcasts.createAudienceImport) | Stores the import as created and answers upload_url, a presigned PUT that lives 15 minutes; needs an Idempotency-Key |
| Upload | PUT <upload_url> | The file as the request body, sent from the browser or a script; no API token rides it |
| Start | POST /v1/audiences/{audience_id}/imports/{import_id}/start (broadcasts.startAudienceImport) | 409 with import.not_uploaded while no file is there, 409 with import.size_mismatch when the file is larger than size_bytes, 409 with import.finished for an import that already ended; otherwise 202 and the import is running (a second start of a running import answers it again) |
| Progress | GET /v1/audiences/{audience_id}/imports/{import_id} (broadcasts.getAudienceImport) | state, rows_total, rows_ok, rows_failed, rows_duplicate and up to 20 failures |
Opening and starting share the import rate class: 5 a minute per API key or member. At most 3 imports run at a time per tenant (a fourth start is 409 with import.concurrent_limit). The states are created, uploaded, running, completed and failed; a finished import is kept for 90 days, then the tenant's next completed import removes it.
The file
- UTF-8 text, a byte order mark is allowed. Fields are separated by commas or semicolons and may be quoted (RFC 4180: a quote inside a quoted field is doubled). Cell values are stored as text and never evaluated, so a cell that starts with
=stays a string. - The first row is the header. Header names are compared trimmed, must be unique, and the file has at most 32 columns.
size_bytesdeclares the file's exact size in bytes when the import is opened, at most 52,428,800 bytes (50 MiB). The upload URL accepts a file of exactly that size and refuses any other.- At most 500,000 data rows. They are read in pages of 50,000 rows, each page in its own run, so a large file survives a restart of the worker in the middle of it.
- A record (one row) has at most 65,536 characters, a physical line at most 4,096 commas or semicolons, and a mapped cell at most 1,024 bytes.
- Rows are numbered as a spreadsheet shows them: the header is row 1, the first contact row 2.
The mapping
mapping.emailnames the header of the address column. Addresses are trimmed and lower-cased, and checked for syntax only (deliverability is the verify product's job).mapping.fieldsmaps up to 20 contact field names to header names. A field name is lower case (^[a-z][a-z0-9_]*$), at most 60 characters, neveremail, and no field may read the address column (422): the address lives in the contact store only.- Unmapped columns are ignored. Empty mapped cells are not written.
- The fields become contact fields of the tenant, usable as segment conditions and as template variables (
{{ first_name }}), except a field namedengagement,consentorstatus(or one starting with those names and a dot): it is stored, but a segment reads those names as its fixed fields. Every write carries the provenancebroadcasts-importwith a confidence of 0.6.
Row results
Each data row ends as one of three counts:
rows_ok: a valid address, written to the contact store and joined to the audience.rows_duplicate: an address that already appeared earlier in the same file (the first one wins).rows_failed: the row is skipped with a code; the first 20 failures are listed with their row number and code, never the value.
| Code | Scope | Meaning |
|---|---|---|
csv.columns | row | the row has another number of columns than the header |
csv.malformed | row | the row is not valid CSV (a stray quote) |
cell.too_long | row | a mapped cell is longer than 1,024 bytes |
email.missing | row | the address cell is empty |
email.invalid | row | the address is not valid |
platform.refused | row | the contact store refused the row |
csv.quote_not_closed | file | a quote is never closed, so the rest of the file cannot be read |
csv.record_too_large | file | a record or a line is past its bound |
import.columns_max | file | more than 32 columns |
import.header_duplicate | file | two header cells have the same name |
import.header_missing | file | the header is missing or a mapped column is not in it |
import.mapping_email | file | the address column is also mapped to a field |
import.rows_max | file | more than 500,000 data rows |
import.pages_max | file | the file needs more pages than one import reads |
import.too_large | file | the file is larger than declared or than 50 MiB |
import.file_missing | file | the file is gone before the import read it |
import.no_progress | file | the import stopped moving: a page read nothing new, or nothing moved for 6 hours (the tenant's next import start ends it) |
import.not_ready | file | a page waited for the page before it past its time |
import.task_refused | file | the import could not run; open a new one |
A row code skips its row and the import goes on. A file code fails the whole import (failed): it is listed first in failures with row: null (the file, not a row) and the uploaded file is deleted. Rows written by earlier pages stay written, so a corrected file can simply be imported again (the contact store updates the existing contacts).
When the import ends
The last page records the totals, deletes the uploaded file and emits audience.import.completed.v1 with the audience, the import, rows_total, rows_ok, rows_failed, rows_duplicate, the consent_source and completed_at: ids, counts and the consent label, never a row. Subscribe to it through webhooks to start a campaign when an import lands.