Contacts

Batch import contacts

POST https://demo.notifuse.com/api/contacts.import

Creates or updates multiple contacts in a single batch operation. This is significantly more efficient than individual upsert operations. Optionally subscribes all contacts to specified lists.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body application/json

workspace_id string required

The ID of the workspace

Example ws_1234567890
contacts object[] required

Array of contacts to import (create or update)

Show 38 child attributes Hide 38 child attributes
email string<email> required

Email address of the contact. This is the contact's unique identifier — upserts always match contacts by email address.

Example user@example.com
external_id string | null

Optional identifier for the contact in your own system (e.g. your user ID). Stored and searchable, but not unique and never used to match contacts during upserts — sending an existing external_id with a new email address creates a second contact.

Example user_12345
timezone string | null

Timezone of the contact

Example America/New_York
language string | null

Preferred language of the contact

Example en-US
first_name string | null

First name of the contact

Example John
last_name string | null

Last name of the contact

Example Doe
full_name string | null

Full name of the contact (for systems that don't have separate first/last names)

Example John Doe
phone string | null

Phone number of the contact

Example +15551234567
address_line_1 string | null

First line of address

Example 123 Main St
address_line_2 string | null

Second line of address

Example Apt 4B
country string | null

Country of the contact

Example US
postcode string | null

Postal code

Example 10001
state string | null

State or province

Example NY
job_title string | null

Job title of the contact

Example Software Engineer
tracking_opens_consent string | null

The contact's own choice about open tracking. granted or denied override the workspace's rule for contacts without a recorded choice; null (or absent on create) means unknown. Opens are tracked only when the workspace tracks them and this choice allows it.

Options granted, denied, null Example denied
tracking_clicks_consent string | null

The contact's own choice about click tracking, with the same rules as tracking_opens_consent.

Options granted, denied, null Example granted
tracking_consent_updated_at string<date-time> | null

When the tracking choice changed. Set by the server when a consent value changes and this field is not given.

tracking_consent_source string | null

Where the change came from. Defaults to api for an API key and console for a console user; an import uses import. Known values: api, console, import, notification_center, email_link, subscribe_form.

Max length 50 Example api
custom_string_1 string | null

Custom string field 1

Example Premium tier
custom_string_2 string | null

Custom string field 2

custom_string_3 string | null

Custom string field 3

custom_string_4 string | null

Custom string field 4

custom_string_5 string | null

Custom string field 5

custom_number_1 number<float> | null

Custom number field 1

Example 42
custom_number_2 number<float> | null

Custom number field 2

custom_number_3 number<float> | null

Custom number field 3

custom_number_4 number<float> | null

Custom number field 4

custom_number_5 number<float> | null

Custom number field 5

custom_datetime_1 string<date-time> | null

Custom datetime field 1

Example 2023-06-01T09:00:00Z
custom_datetime_2 string<date-time> | null

Custom datetime field 2

custom_datetime_3 string<date-time> | null

Custom datetime field 3

custom_datetime_4 string<date-time> | null

Custom datetime field 4

custom_datetime_5 string<date-time> | null

Custom datetime field 5

custom_json_1 any

Custom JSON field 1. Any JSON value the jsonb column can hold — an object, an array, a string, a number, a boolean, or null to clear it.

custom_json_2 any

Custom JSON field 2. Any JSON value the jsonb column can hold.

custom_json_3 any

Custom JSON field 3. Any JSON value the jsonb column can hold.

custom_json_4 any

Custom JSON field 4. Any JSON value the jsonb column can hold.

custom_json_5 any

Custom JSON field 5. Any JSON value the jsonb column can hold.

subscribe_to_lists string[]

Optional array of list IDs to subscribe all contacts to

Response

200 Batch import completed (may include partial failures) object
operations object[]

Array of operation results, one for each contact in the request

Show 3 child attributes Hide 3 child attributes
email string<email>

Email address of the contact

Example user@example.com
action string

The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' for failed operations

Options create, update, error Example create
error string | null

Error message if this specific contact operation failed

error string | null

Global error message if the entire operation failed

400 Bad request - validation failed object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

500 Internal server error object
error string required

Error message