Create or update a contact

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.

{
  "workspace_id": "ws_1234567890",
  "contact": {
    "email": "user@example.com",
    "external_id": "user_12345",
    "timezone": "America/New_York",
    "language": "en-US",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phone": "+15551234567",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "postcode": "10001",
    "state": "NY",
    "job_title": "Software Engineer",
    "custom_string_1": "Premium tier",
    "custom_number_1": 42,
    "custom_datetime_1": "2023-06-01T09:00:00Z",
    "custom_json_1": {
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    }
  }
}

{
  "email": "user@example.com",
  "action": "create"
}