Convert a visitor

You can merge a Visitor to a Contact of role type lead or user.

📘 What happens upon a visitor being converted?

If the User exists, then the Visitor will be merged into it, the Visitor deleted and the User returned. If the User does not exist, the Visitor will be converted to a User, with the User identifiers replacing it's Visitor identifiers.

SecurityHTTP: bearerAuth
Request
header Parameters
Intercom-Version
string (intercom_version)
Default: 2.11

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

Enum: "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" "Unstable"
Example: 2.11
Request Body schema: application/json
type
required
string

Represents the role of the Contact model. Accepts lead or user.

required
object or object

The unique identifiers retained after converting or merging.

required
object or object or object

The unique identifiers to convert a single Visitor.

post
/visitors/convert
Request samples
application/json
{ "visitor": { "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3" }, "user": { "email": "foo@bar.com" }, "type": "user" }
Responses

200

successful

Response Schema: application/json
type
string

The type of object.

id
string

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

external_id
string or null

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

workspace_id
string

The id of the workspace which the contact belongs to.

role
string

The role of the contact.

email
string

The contact's email.

email_domain
string

The contact's email domain.

phone
string or null

The contacts phone.

formatted_phone
string or null

The contacts phone number normalized to the E164 format

name
string or null

The contacts name.

owner_id
integer or null

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

has_hard_bounced
boolean

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

marked_email_as_spam
boolean

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

unsubscribed_from_emails
boolean

Whether the contact is unsubscribed from emails.

created_at
integer <date-time>

(UNIX timestamp) The time when the contact was created.

updated_at
integer <date-time>

(UNIX timestamp) The time when the contact was last updated.

signed_up_at
integer or null <date-time>

(UNIX timestamp) The time specified for when a contact signed up.

last_seen_at
integer or null <date-time>

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

last_replied_at
integer or null <date-time>

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

last_contacted_at
integer or null <date-time>

(UNIX timestamp) The time when the contact was last messaged.

last_email_opened_at
integer or null <date-time>

(UNIX timestamp) The time when the contact last opened an email.

last_email_clicked_at
integer or null <date-time>

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

language_override
string or null

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

browser
string or null

The name of the browser which the contact is using.

browser_version
string or null

The version of the browser which the contact is using.

browser_language
string or null

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

os
string or null

The operating system which the contact is using.

android_app_name
string or null

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

android_app_version
string or null

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

android_device
string or null

The Android device which the contact is using.

android_os_version
string or null

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

android_sdk_version
string or null

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

android_last_seen_at
integer or null <date-time>

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

ios_app_name
string or null

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

ios_app_version
string or null

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

ios_device
string or null

The iOS device which the contact is using.

ios_os_version
string or null

The version of iOS which the contact is using.

ios_sdk_version
string or null

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

ios_last_seen_at
integer or null <date-time>

(UNIX timestamp) The last time the contact used the iOS app.

custom_attributes
object

The custom attributes which are set for the contact.

object or null
object or null (Contact Tags)

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.

object (Contact notes)

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.

object (Contact companies)

An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.

object (Contact Location)

An object containing location meta data about a Intercom contact.

object (Social Profile)

An object containing social profiles that a contact has.

401

Unauthorized

Response samples
application/json
{ "type": "contact", "id": "664df6c56abd01f7945e1bf4", "workspace_id": "this_is_an_id669_that_should_be_at_least_", "external_id": null, "role": "user", "email": "foo@bar.com", "phone": null, "name": null, "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [ ] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1716385477, "updated_at": 1716385478, "signed_up_at": 1716385477, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": { }, "tags": { "type": "list", "data": [ ], "url": "/contacts/664df6c56abd01f7945e1bf4/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [ ], "url": "/contacts/664df6c56abd01f7945e1bf4/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [ ], "url": "/contacts/664df6c56abd01f7945e1bf4/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [ ], "url": "/contacts/664df6c56abd01f7945e1bf4/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [ ], "url": "/contacts/664df6c56abd01f7945e1bf4/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }