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
- Example: ws_1234567890
Show child attributes
Email address of the contact. This is the contact's unique identifier — upserts always match contacts by email address.
- Example: user@example.com
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 of the contact
- Example: America/New_York
Preferred language of the contact
- Example: en-US
First name of the contact
- Example: John
Last name of the contact
- Example: Doe
Full name of the contact (for systems that don't have separate first/last names)
- Example: John Doe
Phone number of the contact
- Example: +15551234567
First line of address
- Example: 123 Main St
Second line of address
- Example: Apt 4B
Country of the contact
- Example: US
Postal code
- Example: 10001
State or province
- Example: NY
Job title of the contact
- Example: Software Engineer
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
The contact's own choice about click tracking, with the same rules as tracking_opens_consent.
- Available options: granted, denied, null
- Example: granted
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.
- Maximum length: 50
- Example: api
Custom string field 1
- Example: Premium tier
Custom string field 2
Custom string field 3
Custom string field 4
Custom string field 5
Custom number field 1
- Example: 42
Custom number field 2
Custom number field 3
Custom number field 4
Custom number field 5
Custom datetime field 1
- Example: 2023-06-01T09:00:00Z
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
- Example: user@example.com
The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' if validation failed
- Available options: create, update, error
- Example: create
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