Intercom API (unofficial showcase)
PUT/contacts/{contact_id}

Update a contact

Replaces the supplied fields on an existing contact, including a user or lead, and can update custom object associations. Send only the fields you want to change; when setting email_verified, include email in the same request. Use include_merge_history to request merge history for contacts with a user role.

3 parameters · 12 body fields
contact_idstringrequired
The unique identifier of the contact to update.
include_merge_historybooleanoptional
Set to true to include merge history for contacts with a user role. Defaults to false when omitted.
Default:false
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Contact fields and custom attributes to update; all listed fields are optional.

rolestringoptional
The role of the contact.
external_idstringoptional
A unique identifier for the contact which is given to Intercom
emailstringoptional
The contacts email
email_verifiedbooleanoptional
Whether the contact has proved they own this email address, for example through a confirmation link or one-time code you sent. Send it together with `email`. `email_verified` without `email` is rejected. Changing a contact's email resets it to not verified. Intercom reuses leads with a verified email when an inbound email, conversation or ticket matches the address.
phonestringoptional
The contacts phone
namestringoptional
The contacts name
avatarstringoptional
An image URL containing the avatar of a contact
signed_up_atintegeroptional
(Unix timestamp in seconds) The time specified for when a contact signed up.
last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
owner_idstringoptional
The id of an admin that has been assigned account ownership of the contact
unsubscribed_from_emailsbooleanoptional
Whether the contact is unsubscribed from emails
custom_attributesobjectoptional
The custom attributes which are set for the contact

2 status codes
200Returns the updated contact object, including its contact details and `enabled_push_messaging` value.
enabled_push_messagingbooleanoptional
If the user has enabled push messaging.
typestringoptional
The type of object.
idstringoptional
The unique identifier for the contact which is given by Intercom.
external_idstringoptional
The unique identifier for the contact which is provided by the Client.
workspace_idstringoptional
The id of the workspace which the contact belongs to.
rolestringoptional
The role of the contact.
emailstringoptional
The contact's email.
email_domainstringoptional
The contact's email domain.
email_verifiedbooleanoptional
Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead.
phonestringoptional
The contacts phone.
namestringoptional
The contacts name.
owner_idstringoptional
The id of an admin that has been assigned account ownership of the contact.
has_hard_bouncedbooleanoptional
Whether the contact has had an email sent to them hard bounce.
marked_email_as_spambooleanoptional
Whether the contact has marked an email sent to them as spam.
unsubscribed_from_emailsbooleanoptional
Whether the contact is unsubscribed from emails.
created_atintegeroptional
(Unix timestamp in seconds) The time when the contact was created.
updated_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last updated.
signed_up_atintegeroptional
(Unix timestamp in seconds) The time specified for when a contact signed up.
last_seen_atintegeroptional
(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_atintegeroptional
(Unix timestamp in seconds) The time when the contact last messaged in.
last_contacted_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last messaged.
last_email_opened_atintegeroptional
(Unix timestamp in seconds) The time when the contact last opened an email.
last_email_clicked_atintegeroptional
(Unix timestamp in seconds) The time when the contact last clicked a link in an email.
language_overridestringoptional
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
browserstringoptional
The name of the browser which the contact is using.
browser_versionstringoptional
The version of the browser which the contact is using.
browser_languagestringoptional
The language set by the browser which the contact is using.
osstringoptional
The operating system which the contact is using.
android_app_namestringoptional
The name of the Android app which the contact is using.
android_app_versionstringoptional
The version of the Android app which the contact is using.
android_devicestringoptional
The Android device which the contact is using.
android_os_versionstringoptional
The version of the Android OS which the contact is using.
android_sdk_versionstringoptional
The version of the Android SDK which the contact is using.
android_last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen on an Android device.
ios_app_namestringoptional
The name of the iOS app which the contact is using.
ios_app_versionstringoptional
The version of the iOS app which the contact is using.
ios_devicestringoptional
The iOS device which the contact is using.
ios_os_versionstringoptional
The version of iOS which the contact is using.
ios_sdk_versionstringoptional
The version of the iOS SDK which the contact is using.
ios_last_seen_atintegeroptional
(Unix timestamp in seconds) The last time the contact used the iOS app.
custom_attributesobjectoptional
The custom attributes which are set for the contact.
avatarobjectoptional
tagsobjectoptional
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
notesobjectoptional
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
companiesobjectoptional
An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.
locationobjectoptional
An object containing location meta data about a Intercom contact.
social_profilesobjectoptional
An object containing social profiles that a contact has.
merge_historyarray<MergeHistoryItem>optional
A list of contacts that were merged into this contact. Only included in the response when `include_merge_history=true` is passed as a query parameter. Only available for contacts with a `user` role.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized. The contact_id path parameter must identify the contact to update. If you set email_verified, include email in the request body; changing a contact's email resets its verification status.