Sign in

v51

latestOpenAPI 3.0.1MITraw.githubusercontent.com2026-08-01150230854.3 KB
Contacts
Custom Object Instances

Update a contact

You can update an existing contact (ie. user or lead).

{% admonition type="info" %} This endpoint handles both contact updates and custom object associations.

See update a contact with an association to a custom object instance in the request/response examples to see the custom object association format. {% /admonition %}

put/contacts/{contact_id}

Path parameters

contact_idstring required

id

Headers

Intercom-Version'1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14'

Intercom API version.</br>By default, it's equal to the version set in the app package.

Example:2.14

Request body

rolestring

The role of the contact.

external_idstring

A unique identifier for the contact which is given to Intercom

emailstring

The contacts email

phonestring nullable

The contacts phone

namestring nullable

The contacts name

avatarstring nullable

An image URL containing the avatar of a contact

signed_up_atinteger nullable

(Unix timestamp in seconds) The time specified for when a contact signed up.

last_seen_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).

owner_idinteger nullable

The id of an admin that has been assigned account ownership of the contact

unsubscribed_from_emailsboolean nullable

Whether the contact is unsubscribed from emails

custom_attributesobject nullable

The custom attributes which are set for the contact

Example request

{
  "email": "jdoe@example.com",
  "phone": "+353871234567",
  "name": "John Doe",
  "avatar": "https://www.example.com/avatar_image.jpg",
  "signed_up_at": 1571672154,
  "last_seen_at": 1571672154,
  "owner_id": 123,
  "unsubscribed_from_emails": true
}

Response

successful

typestring

The type of object.

idstring

The unique identifier for the contact which is given by Intercom.

external_idstring nullable

The unique identifier for the contact which is provided by the Client.

workspace_idstring

The id of the workspace which the contact belongs to.

rolestring

The role of the contact.

emailstring

The contact's email.

email_domainstring

The contact's email domain.

phonestring nullable

The contacts phone.

namestring nullable

The contacts name.

owner_idinteger nullable

The id of an admin that has been assigned account ownership of the contact.

has_hard_bouncedboolean

Whether the contact has had an email sent to them hard bounce.

marked_email_as_spamboolean

Whether the contact has marked an email sent to them as spam.

unsubscribed_from_emailsboolean

Whether the contact is unsubscribed from emails.

created_atinteger

(Unix timestamp in seconds) The time when the contact was created.

updated_atinteger

(Unix timestamp in seconds) The time when the contact was last updated.

signed_up_atinteger nullable

(Unix timestamp in seconds) The time specified for when a contact signed up.

last_seen_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).

last_replied_atinteger nullable

(Unix timestamp in seconds) The time when the contact last messaged in.

last_contacted_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last messaged.

last_email_opened_atinteger nullable

(Unix timestamp in seconds) The time when the contact last opened an email.

last_email_clicked_atinteger nullable

(Unix timestamp in seconds) The time when the contact last clicked a link in an email.

language_overridestring nullable

A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.

browserstring nullable

The name of the browser which the contact is using.

browser_versionstring nullable

The version of the browser which the contact is using.

browser_languagestring nullable

The language set by the browser which the contact is using.

osstring nullable

The operating system which the contact is using.

android_app_namestring nullable

The name of the Android app which the contact is using.

android_app_versionstring nullable

The version of the Android app which the contact is using.

android_devicestring nullable

The Android device which the contact is using.

android_os_versionstring nullable

The version of the Android OS which the contact is using.

android_sdk_versionstring nullable

The version of the Android SDK which the contact is using.

android_last_seen_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last seen on an Android device.

ios_app_namestring nullable

The name of the iOS app which the contact is using.

ios_app_versionstring nullable

The version of the iOS app which the contact is using.

ios_devicestring nullable

The iOS device which the contact is using.

ios_os_versionstring nullable

The version of iOS which the contact is using.

ios_sdk_versionstring nullable

The version of the iOS SDK which the contact is using.

ios_last_seen_atinteger nullable

(Unix timestamp in seconds) The last time the contact used the iOS app.

custom_attributesobject

The custom attributes which are set for the contact.

Example response

{
  "type": "contact",
  "id": "5ba682d23d7cf92bef87bfd4",
  "external_id": "f3b87a2e09d514c6c2e79b9a",
  "workspace_id": "ecahpwf5",
  "role": "user",
  "email": "joe@example.com",
  "email_domain": "example.com",
  "phone": "+1123456789",
  "name": "John Doe",
  "owner_id": 123,
  "has_hard_bounced": true,
  "marked_email_as_spam": true,
  "unsubscribed_from_emails": true,
  "created_at": 1571672154,
  "updated_at": 1571672154,
  "signed_up_at": 1571672154,
  "last_seen_at": 1571672154,
  "last_replied_at": 1571672154,
  "last_contacted_at": 1571672154,
  "last_email_opened_at": 1571672154,
  "last_email_clicked_at": 1571672154,
  "language_override": "en",
  "browser": "Chrome",
  "browser_version": "80.0.3987.132",
  "browser_language": "en-US",
  "os": "Mac OS X",
  "android_app_name": "Intercom",
  "android_app_version": "5.0.0",
  "android_device": "Pixel 3",
  "android_os_version": "10",
  "android_sdk_version": "28",
  "android_last_seen_at": 1571672154,
  "ios_app_name": "Intercom",
  "ios_app_version": "5.0.0",
  "ios_device": "iPhone 11",
  "ios_os_version": "13.3.1",
  "ios_sdk_version": "13.3.1",
  "ios_last_seen_at": 1571672154,
  "avatar": {
    "type": "avatar",
    "image_url": "https://example.org/128Wash.jpg"
  },
  "tags": {
    "data": [
      {
        "type": "note",
        "id": "123",
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags",
    "total_count": 100,
    "has_more": true
  },
  "notes": {
    "data": [
      {
        "type": "note",
        "id": "123",
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes",
    "total_count": 100,
    "has_more": true
  },
  "companies": {
    "data": [
      {
        "id": "5ba682d23d7cf92bef87bfd4",
        "type": "company",
        "url": "/companies/5ba682d23d7cf92bef87bfd4"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies",
    "total_count": 100,
    "has_more": true
  },
  "location": {
    "type": "location",
    "country": "Ireland",
    "region": "Dublin",
    "city": "Dublin"
  },
  "social_profiles": {
    "data": [
      {
        "type": "social_profile",
        "name": "Facebook",
        "url": "http://twitter.com/th1sland"
      }
    ]
  }
}