Contacts

Create or update a contact

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

Creates a new contact or updates an existing one. Contacts are matched by email address only — the email is the contact's unique identifier. external_id is stored but never used for matching, so sending an existing external_id with a new email address creates a second contact.

To change a contact's email address: upsert a contact with the new email and the full profile, re-create its list subscriptions (preserving unsubscribed/bounced/complained statuses — do not reset opt-outs), then delete the contact with the old email using contacts.delete. Message history and segment memberships are keyed to the email address and are not transferred.

Returns information about whether the contact was created or updated.

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
contact object required
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.

Response

200 Contact upserted successfully object
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' if validation failed

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

Error message if the 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