Intercom API (unofficial showcase)
POST/visitors/convert

Convert a visitor to a contact

Converts a visitor into a contact with the specified lead or user role, merging the visitor into an existing contact when one matches. If no matching contact exists, the visitor's identifiers are replaced with the supplied contact identifiers. The response contains the resulting contact.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
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

The contact role and identifiers for the contact and visitor involved in the conversion.

typestringrequired
Represents the role of the Contact model. Accepts `lead` or `user`.
userobjectrequired
The unique identifiers retained after converting or merging.
visitorobjectrequired
The unique identifiers to convert a single Visitor.

2 status codes
200Returns the resulting contact object, including its identifiers, role, and profile details.
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 body requires type, user, and visitor; type must be lead or user, and user and visitor must each include at least one accepted identifier.