Skip to content
Home/
REST API Reference
/
/
Update a visitor

Update a visitor

Request

Sending a PUT request to /visitors will result in an update of an existing Visitor.

Option 1. You can update a visitor by passing in the user_id of the visitor in the Request body.

Option 2. You can update a visitor by passing in the id of the visitor in the Request body.

Sending an email promotes the visitor to a lead. When that happens the response is a contact object with a role of lead, not a visitor object.

Requires the read_write_users or write_users_companies OAuth scope.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
Bodyapplication/json
Any of:

Update an existing visitor.

idstring

A unique identified for the visitor which is given by Intercom. Used to look the visitor up; it is not changed by this request.

Example:"8a88a590-e"
user_idstring

A unique identified for the visitor which is given by you. Used to look the visitor up; it is not changed by this request.

Example:"123"
namestring

The visitor's name.

Example:"Christian Bale"
emailstring

The visitor's email address. Sending this promotes the visitor to a lead and the response becomes a contact object.

Example:"winstonsmith@truth.org"
phonestring

The visitor's phone number.

Example:"+353871234567"
owner_idinteger

The id of the teammate who owns the visitor.

Example:991267734
last_request_atinteger

The time the visitor was last seen, as a Unix timestamp.

Example:1663597223
last_seen_ipstring

The IP address the visitor was last seen from.

Example:"1.2.3.4"
last_seen_user_agentstring

The user agent the visitor was last seen with.

Example:"Mozilla/5.0"
unsubscribed_from_emailsboolean

Whether the visitor is unsubscribed from emails.

Example:false
language_overridestring

The language to send the visitor messages in, overriding the language we detect.

Example:"fr"
avatarstring

An image URL for the visitor's avatar.

Example:"https://example.org/128Wu8Q.jpg"
companiesArray of objects

The companies to associate the visitor with. Only applied when the same request sends email, which promotes the visitor to a lead.

utm_campaignstring

The campaign the visitor arrived from.

Example:"intercom-link"
utm_contentstring

The content the visitor arrived from.

Example:"banner"
utm_mediumstring

The medium the visitor arrived from.

Example:"email"
utm_sourcestring

The source the visitor arrived from.

Example:"Intercom"
utm_termstring

The search term the visitor arrived from.

Example:"messenger"
custom_attributesobject

The custom attributes which are set for the visitor.

Example:
{
  "paid_subscriber": true,
  "monthly_spend": 155.5,
  "team_mates": 9
}
curl -i -X PUT \
  https://api.intercom.io/visitors \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "id": "6762f30c1bb69f9f2193bc5e",
    "name": "Gareth Bale"
  }'

Responses

successful

Bodyapplication/json
typestring

Value is 'visitor'

Default:"visitor"
Example:"visitor"
idstring

The Intercom defined id representing the Visitor.

Example:"530370b477ad7120001d"
user_idstring

Automatically generated identifier for the Visitor.

Example:"8a88a590-e1c3-41e2-a502-e0649dbf721c"
anonymousboolean

Identifies if this visitor is anonymous.

Example:false
emailstring, (email)

The email of the visitor.

Example:"jane.doe@example.com"
phonestring or null

The phone number of the visitor.

Example:"555-555-5555"
namestring or null

The name of the visitor.

Example:"Jane Doe"
pseudonymstring or null

The pseudonym of the visitor.

Example:"Red Duck from Dublin"
avatarobject
app_idstring

The id of the app the visitor is associated with.

Example:"hfi1bx4l"
companiesobject
location_dataobject
last_request_atinteger

The time the Lead last recorded making a request.

Example:1663597260
created_atinteger

The time the Visitor was added to Intercom.

Example:1663597223
remote_created_atinteger

The time the Visitor was added to Intercom.

Example:1663597223
signed_up_atinteger

The time the Visitor signed up for your product.

Example:1663597223
updated_atinteger

The last time the Visitor was updated.

Example:1663597260
session_countinteger

The number of sessions the Visitor has had.

Example:1
social_profilesobject
owner_idstring or null

The id of the admin that owns the Visitor.

Example:"5169261"
unsubscribed_from_emailsboolean

Whether the Visitor is unsubscribed from emails.

Example:false
marked_email_as_spamboolean

Identifies if this visitor has marked an email as spam.

Example:false
has_hard_bouncedboolean

Identifies if this visitor has had a hard bounce.

Example:false
tagsobject
segmentsobject
custom_attributesobject

The custom attributes you have set on the Visitor.

referrerstring or null

The referer of the visitor.

Example:"https://www.google.com/"
utm_campaignstring or null

The utm_campaign of the visitor.

Example:"intercom-link"
utm_contentstring or null

The utm_content of the visitor.

Example:"banner"
utm_mediumstring or null

The utm_medium of the visitor.

Example:"email"
utm_sourcestring or null

The utm_source of the visitor.

Example:"Intercom"
utm_termstring or null

The utm_term of the visitor.

Example:"messenger"
do_not_trackboolean or null

Identifies if this visitor has do not track enabled.

Example:false
Response
{
  "type": "visitor",
  "id": "6762f30c1bb69f9f2193bc5e",
  "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3",
  "anonymous": true,
  "email": "",
  "phone": null,
  "name": "Gareth Bale",
  "pseudonym": "Violet Suitcase",
  "avatar": {
    "type": "avatar",
    "image_url": "https://static.intercomassets.com/app/pseudonym_avatars_2019/violet-suitcase.png"
  },
  "app_id": "this_is_an_id716_that_should_be_at_least_",
  "companies": {
    "type": "company.list",
    "companies": []
  },
  "location_data": {},
  "last_request_at": null,
  "created_at": 1734537996,
  "remote_created_at": 1734537996,
  "signed_up_at": 1734537996,
  "updated_at": 1734537997,
  "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
}