DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour 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": {
    "type":"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": {
    "type":"social_profile.list",
    "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

Attribute

Type

Description

type

string

Value is 'user' or 'contact'

id

string

The Intercom defined id representing the user

created_at

timestamp

The time (in seconds) the user was added to Intercom

signed_up_at

timestamp

The time (in seconds) the user signed up

updated_at

timestamp

The last time the user was updated

user_id

string

The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)

email

string

The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)

phone

string

The phone number of the user

custom_attributes

object

The custom attributes you have set on the user (case sensitive).

last_request_at

timestamp

The time the user last recorded making a request

session_count

integer

How many sessions the user has recorded

avatar

object

An avatar object for the user.

unsubscribed_from_emails

boolean

Whether the user is unsubscribed from emails

location_data

object

A Location Object relating to the user

user_agent_data

string

Data about the last user agent the user was seen using

last_seen_ip

null

This will return null in an effort to remove PII from our API.

pseudonym

string

The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)

anonymous

boolean

Whether or not this is a Lead. Always false

companies

list

A list of companies for the user

social_profiles

list

A list of social profiles associated with the user

segments

list

This 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.

tags

list

A list of tags associated with the user

name

string

The full name of the user

referrer

string

The URL of the page the user was last on

utm_source

string

Identifies which site sent the traffic

utm_medium

string

Identifies what type of link was used

utm_campaign

string

Identifies a specific product promotion or strategic campaign

utm_term

string

Identifies search terms

utm_content

string

Identifies 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

Attribute

Type

Description

type

string

Value is 'social_profile'

name

string

The name of the service (e.g., twitter, facebook)

username

string

User name or handle on the service

url

string

The user homepage on the service

id

string

Optional. User ID on the service

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

Avatar Object

Attribute

Type

Description

type

string

Value is 'avatar'

image_url

string

An avatar image URL. note: the image url needs to be https.

Location Object

Attribute

Type

Description

type

string

Value is 'location_data'

city_name

string

Optional. A city name

continent_code

string

Optional. A continent code

country_code

string

Optional. An ISO 3166 country code

country_name

string

Optional. The country name

latitude

number

Optional. The latitude

longitude

number

Optional. The longitude

postal_code

string

Optional. A postal code

region_name

string

Optional. A region name

timezone

string

Optional. An ISO 8601 timezone

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

User List

Attribute

Type

Description

type

string

Value is 'user.list'

total_count

integer

The number of users for this app

pages

object

A Pagination object

users

array

A 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.