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 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.

  • Available 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.

  • Available 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.

  • Maximum 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 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

  • Available 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