API ReferenceBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreCommunityBlogYour Apps

User Model

Example User Object (i.e. example JSON response)

  "type": "user",
  "id": "530370b477ad7120001d",
  "user_id": "25",
  "email": "[email protected]",
  "phone": "+1123456789",
  "name": "Hoban Washburne",
  "updated_at": 1392734388,
  "last_seen_ip" : null,
  "unsubscribed_from_emails": false,
  "last_request_at": 1397574667,
  "signed_up_at": 1392731331,
  "created_at": 1392734388,
  "session_count": 179,
  "user_agent_data": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9",
  "pseudonym": null,
  "anonymous": false,
  "referrer": "https://example.org",
  "owner_id": "321452",
  "utm_campaign": null,
  "utm_content": null,
  "utm_medium": null,
  "utm_source": null,
  "utm_term": null,
  "custom_attributes": {
    "paid_subscriber" : true,
    "monthly_spend": 155.5,
    "team_mates": 1
  "avatar": {
    "image_url": "https://example.org/128Wash.jpg"
  "location_data": {
      "type": "location_data",
      "city_name": "Dublin",
      "continent_code": "EU",
      "country_code": "IRL",
      "country_name": "Ireland",
      "latitude": 53.159233,
      "longitude": -6.723,
      "postal_code": null,
      "region_name": "Dublin",
      "timezone": "Europe/Dublin"
  "social_profiles": {
    "social_profiles": [
        "name": "Twitter",
        "id": "1235d3213",
        "username": "th1sland",
        "url": "http://twitter.com/th1sland"
  "companies": {
    "type": "company.list",
    "companies": [
        "id" : "530370b477ad7120001e"
  "segments": {
    "type": "segment.list",
    "segments": [ ]
  "tags": {
    "type": "tag.list",
    "tags": [
        "id": "202"
Example List of Users

  "type": "user.list",
  "total_count": 1, 
  "users": [
    # an array of user objects
  "pages": {}

User Object

A user object contains the following fields

typestringValue is 'user' or 'contact'
idstringThe Intercom defined id representing the user
created_attimestampThe time (in seconds) the user was added to Intercom
signed_up_attimestampThe time (in seconds) the user signed up
updated_attimestampThe last time the user was updated
user_idstringThe user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)
emailstringThe email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)
phonestringThe phone number of the user
custom_attributesobjectThe custom attributes you have set on the user (case sensitive).
last_request_attimestampThe time the user last recorded making a request
session_countintegerHow many sessions the user has recorded
avatarobjectAn avatar object for the user.
unsubscribed_from_emailsbooleanWhether the user is unsubscribed from emails
location_dataobjectA Location Object relating to the user
user_agent_datastringData about the last user agent the user was seen using
last_seen_ipnullThis will return null in an effort to remove PII from our API.
pseudonymstringThe pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)
anonymousbooleanWhether or not this is a Lead. Always false
companieslistA list of companies for the user
social_profileslistA list of social profiles associated with the user
segmentslistThis will return an empty list of segments as part of our effort to deprecate this attribute on the user model for performance and accuracy reasons.
tagslistA list of tags associated with the user
namestringThe full name of the user
referrerstringThe URL of the page the user was last on
utm_sourcestringIdentifies which site sent the traffic
utm_mediumstringIdentifies what type of link was used
utm_campaignstringIdentifies a specific product promotion or strategic campaign
utm_termstringIdentifies search terms
utm_contentstringIdentifies what specifically was clicked to bring the user to the site

Note that in some parts of the API, the user id field may be referred to using intercom_user_id.
Any integer values in the user model are limited to the int32 range -2^31 to 2^31 -1

Social Profile Object

typestringValue is 'social_profile'
namestringThe name of the service (e.g., twitter, facebook)
usernamestringUser name or handle on the service
urlstringThe user homepage on the service
idstringOptional. User ID on the service

Social data is read only and can not be updated via the API.

Avatar Object

typestringValue is 'avatar'
image_urlstringAn avatar image URL. note: the image url needs to be https.

Location Object

typestringValue is 'location_data'
city_namestringOptional. A city name
continent_codestringOptional. A continent code
country_codestringOptional. An ISO 3166 country code
country_namestringOptional. The country name
latitudenumberOptional. The latitude
longitudenumberOptional. The longitude
postal_codestringOptional. A postal code
region_namestringOptional. A region name
timezonestringOptional. An ISO 8601 timezone

Location data is read only and can not be updated via the API.

User List

typestringValue is 'user.list'
total_countintegerThe number of users for this app
pagesobjectA Pagination object
usersarrayA list of users

The user list does not return Leads - this means all objects in the list will have an anonymous value of false. Any user in the list that was converted from a Lead will retain their pseudonym value.