Sign in

v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB
Contact

Upsert a Contact

Creates or updates a Contact, matching on the email address. If the Contact does not exist, it will be created. If the Contact does exist, it will be updated. It is not possible to delete a Contact via this endpoint. It is not possible to reset properties of a Contact by passing empty values. E.g. passing null for first_name or an empty array for tag_ids won't update previous values. To do that you would instead need to use the Update Contact endpoint.

post/workspaces/{workspace_id}/contacts/upsert

Path parameters

workspace_idinteger required

Query parameters

expand[]string[]

Expand additional data in the response. Use expand[]=field_name to include optional fields (e.g., expand[]=email_engagement). See the Expanding guide for available fields and examples.

Request body

Example request

{
  "contact": {
    "contact": {
      "email_address": "test-4059727ec8e173ce4648@example.com",
      "first_name": "Sol",
      "last_name": "Jones",
      "phone_number": "(224) 508-1342 x59891",
      "time_zone": "Pacific Time (US & Canada)",
      "fb_url": "https://www.facebook.com/example",
      "twitter_url": "https://twitter.com/example",
      "instagram_url": null,
      "linkedin_url": "https://www.linkedin.com/in/example",
      "website_url": "https://example.com"
    }
  }
}

Response

OK

idinteger

Contact ID

public_idstring

Contact public ID

workspace_idinteger

Workspace ID

anonymousinteger nullable

Anonymous

email_addressstring nullable

The contact's email address. It is currently not expected to be null and is the main identifier for a contact.

first_namestring nullable

First name

last_namestring nullable

Last name

phone_numberstring nullable

Phone number

time_zonestring nullable

The human-readable time zone, usually set dynamically by the app for the contact, for example, during opt-in. Read more about time zones and how to map them back to the TZ standard in our Time Zones guide..

uuidstring

UUID

unsubscribed_atstring nullable

Unsubscribed

last_notification_email_sent_atstring nullable

Last notification email sent

email_suppression_reasonstring nullable

The reason the contact's email address is suppressed from receiving emails. Null when no suppression exists.

is_activeboolean

Whether the contact is active. A contact is considered active when they have a valid email address, have not unsubscribed, have not been deleted, and have no email suppression reason.

fb_urlstring nullable

Facebook URL

twitter_urlstring nullable

Twitter URL

instagram_urlstring nullable

Instagram URL

linkedin_urlstring nullable

LinkedIn URL

website_urlstring nullable

Website URL

created_atstring date-time

Date added

updated_atstring date-time

Last updated

custom_attributesobject

A dynamic key-value pair object where both the key and value are strings. Custom attributes are usually added to the contact when they submit forms that contain custom contact attributes. But you can also add them via the API using the modifying endpoints like Create/Update/Upsert Contact.

Example response

{
  "id": 24359,
  "public_id": "vQxYMj",
  "workspace_id": 4,
  "anonymous": 0,
  "email_address": "jane.doe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "+18005550199",
  "time_zone": "Madrid",
  "uuid": "80b7f903-76cd-4edf-94bf-fc34c13ee654",
  "unsubscribed_at": null,
  "last_notification_email_sent_at": null,
  "email_suppression_reason": null,
  "is_active": true,
  "fb_url": null,
  "twitter_url": null,
  "instagram_url": null,
  "linkedin_url": null,
  "website_url": null,
  "created_at": "2026-01-09T15:27:56.647Z",
  "updated_at": "2026-01-09T15:28:08.075Z",
  "tags": [],
  "custom_attributes": {},
  "visits": {
    "first_visit": {
      "uuid": "9f2e8a22-1b65-4414-95f3-5caf0bbd11da",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale",
      "utm_term": "running shoes",
      "utm_content": "ad_variant_a",
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
      "referrer": "https://www.google.com/search?q=example",
      "referring_domain": "google.com",
      "landing_page": "https://example.com/products/shoes",
      "browser": "Chrome",
      "os": "Mac OS X",
      "device_type": "desktop",
      "started_at": "2026-01-09T14:23:45.123Z",
      "created_at": "2026-01-09T14:23:45.123Z",
      "updated_at": "2026-01-09T14:23:45.123Z"
    },
    "last_visit": null,
    "last_visit_with_utm": {
      "uuid": "9f2e8a22-1b65-4414-95f3-5caf0bbd11da",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale",
      "utm_term": "running shoes",
      "utm_content": "ad_variant_a",
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
      "referrer": "https://www.google.com/search?q=example",
      "referring_domain": "google.com",
      "landing_page": "https://example.com/products/shoes",
      "browser": "Chrome",
      "os": "Mac OS X",
      "device_type": "desktop",
      "started_at": "2026-01-09T14:23:45.123Z",
      "created_at": "2026-01-09T14:23:45.123Z",
      "updated_at": "2026-01-09T14:23:45.123Z"
    }
  }
}