API · Contact imports

Create Contact Import

Import contacts from a CSV file (requires full access). Existing contacts are updated by default, and contact webhooks are not emitted for imported rows.

POST/contacts/importsFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`file` body · required	`string`	CSV file limited to 500 rows and 500 KB of parsed data, within a 1 MiB multipart request.
`column_map` body · optional	`string`	JSON-encoded field-to-column map; custom properties support string and number values, with boolean properties rejected.
`on_conflict` body · optional	`"upsert" \| "skip"`	How to handle existing contacts, defaulting to upsert.
`segments` body · optional	`string`	JSON-encoded array of segments to add imported contacts to.
`topics` body · optional	`string`	JSON-encoded topic subscriptions with each subscription set to opt_in or opt_out.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

csv

email,first_name
you@example.net,Ada

bash

curl -X POST "$OPENSEND_BASE_URL/contacts/imports" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -F 'file=@contacts.csv' \
  --form-string 'on_conflict=upsert'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Behavior and errors

Upload multipart CSV, not JSON. Save the sample CSV above as contacts.csv before running cURL. The SDK options are columnMap and onConflict; the form fields are column_map and on_conflict. Imports accept 1–500 rows, a 1 MiB request and at most 500 KB of parsed job data. Contact webhooks are suppressed. See contact imports.

Use a full-access credential. Unknown or foreign resources return 404. See authentication, errors, rate limits, and pagination.