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
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Body application/json
The ID of the workspace
Show 38 child attributes Hide 38 child attributes
Email address of the contact. This is the contact's unique identifier — upserts always match contacts by email address.
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.
Timezone of the contact
Preferred language of the contact
First name of the contact
Last name of the contact
Full name of the contact (for systems that don't have separate first/last names)
Phone number of the contact
First line of address
Second line of address
Country of the contact
Postal code
State or province
Job title of the contact
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.
The contact's own choice about click tracking, with the same rules as tracking_opens_consent.
When the tracking choice changed. Set by the server when a consent value changes and this field is not given.
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.
Custom string field 1
Custom string field 2
Custom string field 3
Custom string field 4
Custom string field 5
Custom number field 1
Custom number field 2
Custom number field 3
Custom number field 4
Custom number field 5
Custom datetime field 1
Custom datetime field 2
Custom datetime field 3
Custom datetime field 4
Custom datetime field 5
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 field 2. Any JSON value the jsonb column can hold.
Custom JSON field 3. Any JSON value the jsonb column can hold.
Custom JSON field 4. Any JSON value the jsonb column can hold.
Custom JSON field 5. Any JSON value the jsonb column can hold.
Response
200 Contact upserted successfully object
Email address of the contact
The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' if validation failed
Error message if the operation failed
400 Bad request - validation failed object
Error message
401 Unauthorized - invalid or missing authentication token object
Error message
500 Internal server error object
Error message