The intercom API reference.
The intercom API reference.
Update an existing visitor.
A unique identified for the visitor which is given by Intercom.
curl -i -X PUT \
https://api.intercom.io/visitors \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.11' \
-d '{
"id": "667d61cc8a68186f43bafe95",
"name": "Gareth Bale"
}'
{ "type": "visitor", "id": "667d61cc8a68186f43bafe95", "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3", "anonymous": true, "email": "", "phone": null, "name": "Gareth Bale", "pseudonym": "Indigo Ghost", "avatar": { "type": "avatar", "image_url": "https://static.intercomassets.com/app/pseudonym_avatars_2019/indigo-ghost.png" }, "app_id": "this_is_an_id671_that_should_be_at_least_", "companies": { "type": "company.list", "companies": [] }, "location_data": {}, "last_request_at": null, "created_at": 1719493068, "remote_created_at": 1719493068, "signed_up_at": 1719493068, "updated_at": 1719493068, "session_count": 0, "social_profiles": { "type": "social_profile.list", "social_profiles": [] }, "owner_id": null, "unsubscribed_from_emails": false, "marked_email_as_spam": false, "has_hard_bounced": false, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "custom_attributes": {}, "referrer": null, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "do_not_track": null }
curl -i -X GET \
'https://api.intercom.io/visitors?user_id=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'
{ "type": "visitor", "id": "667d61ce8a68186f43bafe9b", "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3", "anonymous": true, "email": "", "phone": null, "name": null, "pseudonym": null, "avatar": { "type": "avatar", "image_url": null }, "app_id": "this_is_an_id677_that_should_be_at_least_", "companies": { "type": "company.list", "companies": [] }, "location_data": {}, "last_request_at": null, "created_at": 1719493070, "remote_created_at": 1719493070, "signed_up_at": 1719493070, "updated_at": 1719493070, "session_count": 0, "social_profiles": { "type": "social_profile.list", "social_profiles": [] }, "owner_id": null, "unsubscribed_from_emails": false, "marked_email_as_spam": false, "has_hard_bounced": false, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "custom_attributes": {}, "referrer": null, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "do_not_track": null }
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.
The unique identifiers retained after converting or merging.
The unique identifiers retained after converting or merging.
The unique identifier for the contact which is given by Intercom.
A unique identifier for the contact which is given to Intercom, which will be represented as external_id.
The unique identifiers to convert a single Visitor.
The unique identifiers to convert a single Visitor.
The unique identifier for the contact which is given by Intercom.
A unique identifier for the contact which is given to Intercom.
curl -i -X POST \
https://api.intercom.io/visitors/convert \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.11' \
-d '{
"visitor": {
"user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3"
},
"user": {
"email": "foo@bar.com"
},
"type": "user"
}'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
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.
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.
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.
{ "type": "contact", "id": "667d61d08a68186f43bafea2", "workspace_id": "this_is_an_id683_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": 1719493072, "updated_at": 1719493072, "signed_up_at": 1719493072, "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/667d61d08a68186f43bafea2/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/667d61d08a68186f43bafea2/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/667d61d08a68186f43bafea2/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/667d61d08a68186f43bafea2/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/667d61d08a68186f43bafea2/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }