---
title: "Create or update a contact"
method: POST
path: "/api/contacts.upsert"
---

# Create or update a contact

`POST /api/contacts.upsert`

Creates a new contact or updates an existing one based on email address. Returns information about whether the contact was created or updated.

## Request body

- UpsertContactRequest
  - `workspace_id` string, required — The ID of the workspace
  - `contact` Contact, required
    - `email` string, email, required — Email address of the contact
    - `external_id` string, nullable — External identifier for the contact
    - `timezone` string, nullable — Timezone of the contact
    - `language` string, nullable — Preferred language of the contact
    - `first_name` string, nullable — First name of the contact
    - `last_name` string, nullable — Last name of the contact
    - `phone` string, nullable — Phone number of the contact
    - `address_line_1` string, nullable — First line of address
    - `address_line_2` string, nullable — Second line of address
    - `country` string, nullable — Country of the contact
    - `postcode` string, nullable — Postal code
    - `state` string, nullable — State or province
    - `job_title` string, nullable — Job title of the contact
    - `custom_string_1` string, nullable — Custom string field 1
    - `custom_string_2` string, nullable — Custom string field 2
    - `custom_string_3` string, nullable — Custom string field 3
    - `custom_string_4` string, nullable — Custom string field 4
    - `custom_string_5` string, nullable — Custom string field 5
    - `custom_number_1` number, float, nullable — Custom number field 1
    - `custom_number_2` number, float, nullable — Custom number field 2
    - `custom_number_3` number, float, nullable — Custom number field 3
    - `custom_number_4` number, float, nullable — Custom number field 4
    - `custom_number_5` number, float, nullable — Custom number field 5
    - `custom_datetime_1` string, date-time, nullable — Custom datetime field 1
    - `custom_datetime_2` string, date-time, nullable — Custom datetime field 2
    - `custom_datetime_3` string, date-time, nullable — Custom datetime field 3
    - `custom_datetime_4` string, date-time, nullable — Custom datetime field 4
    - `custom_datetime_5` string, date-time, nullable — Custom datetime field 5
    - `custom_json_1` object, nullable — Custom JSON field 1
    - `custom_json_2` object, nullable — Custom JSON field 2
    - `custom_json_3` object, nullable — Custom JSON field 3
    - `custom_json_4` object, nullable — Custom JSON field 4
    - `custom_json_5` object, nullable — Custom JSON field 5
    - `created_at` string, date-time — When the contact was created
    - `updated_at` string, date-time — When the contact was last updated
    - `contact_lists` ContactList[] — Lists the contact is subscribed to (only included in GET endpoints)
      - `email` string, email — Email address of the contact
      - `list_id` string — ID of the list
      - `list_name` string — Name of the list
      - `status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' — Subscription status
      - `created_at` string, date-time — When the contact was subscribed to this list
      - `updated_at` string, date-time — When the subscription was last updated
      - `deleted_at` string, date-time, nullable — When the subscription was deleted (null if active)

## Response `200`

Contact upserted successfully

- UpsertContactResponse
  - `action` 'created' | 'updated' | 'unchanged' — The action that was performed on the contact
  - `contact` Contact
    - `email` string, email, required — Email address of the contact
    - `external_id` string, nullable — External identifier for the contact
    - `timezone` string, nullable — Timezone of the contact
    - `language` string, nullable — Preferred language of the contact
    - `first_name` string, nullable — First name of the contact
    - `last_name` string, nullable — Last name of the contact
    - `phone` string, nullable — Phone number of the contact
    - `address_line_1` string, nullable — First line of address
    - `address_line_2` string, nullable — Second line of address
    - `country` string, nullable — Country of the contact
    - `postcode` string, nullable — Postal code
    - `state` string, nullable — State or province
    - `job_title` string, nullable — Job title of the contact
    - `custom_string_1` string, nullable — Custom string field 1
    - `custom_string_2` string, nullable — Custom string field 2
    - `custom_string_3` string, nullable — Custom string field 3
    - `custom_string_4` string, nullable — Custom string field 4
    - `custom_string_5` string, nullable — Custom string field 5
    - `custom_number_1` number, float, nullable — Custom number field 1
    - `custom_number_2` number, float, nullable — Custom number field 2
    - `custom_number_3` number, float, nullable — Custom number field 3
    - `custom_number_4` number, float, nullable — Custom number field 4
    - `custom_number_5` number, float, nullable — Custom number field 5
    - `custom_datetime_1` string, date-time, nullable — Custom datetime field 1
    - `custom_datetime_2` string, date-time, nullable — Custom datetime field 2
    - `custom_datetime_3` string, date-time, nullable — Custom datetime field 3
    - `custom_datetime_4` string, date-time, nullable — Custom datetime field 4
    - `custom_datetime_5` string, date-time, nullable — Custom datetime field 5
    - `custom_json_1` object, nullable — Custom JSON field 1
    - `custom_json_2` object, nullable — Custom JSON field 2
    - `custom_json_3` object, nullable — Custom JSON field 3
    - `custom_json_4` object, nullable — Custom JSON field 4
    - `custom_json_5` object, nullable — Custom JSON field 5
    - `created_at` string, date-time — When the contact was created
    - `updated_at` string, date-time — When the contact was last updated
    - `contact_lists` ContactList[] — Lists the contact is subscribed to (only included in GET endpoints)
      - `email` string, email — Email address of the contact
      - `list_id` string — ID of the list
      - `list_name` string — Name of the list
      - `status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' — Subscription status
      - `created_at` string, date-time — When the contact was subscribed to this list
      - `updated_at` string, date-time — When the subscription was last updated
      - `deleted_at` string, date-time, nullable — When the subscription was deleted (null if active)
  - `error` string, nullable — Error message if the operation failed

## Other responses

- `400` — Bad request - validation failed
- `401` — Unauthorized - invalid or missing authentication token
- `500` — Internal server error

## Changes

- **2025-11-29** `c39acad12e49` — 6 warning
  - removed the request property `contact/last_order_at`
  - removed the request property `contact/lifetime_value`
  - removed the request property `contact/orders_count`
  - removed the optional property `contact/last_order_at` from the response with the `200` status
  - …2 more
- **2025-11-01** `6d2b86adbdc3` — 2 info
  - added the new optional request property `contact/contact_lists`
  - added the optional property `contact/contact_lists` to the response with the `200` status
- **2025-08-24** `384ae1bf1437` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/contacts.upsert/post.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/c39acad12e49/schema)