The Contact Model

The Contacts API is a central place to gather all information and take actions on your contacts (ie. users and leads), such as fetching, searching, creating, updating, and deleting.

The Contact Model provides details on these contacts within Intercom, and will specify whether they are a user or lead through the role attribute.

Example Contact Object

JSON

{
  "type": "contact",
  "id": "5ba682d23d7cf92bef87bfd4",
  "workspace_id": "ecahpwf5",
  "external_id": "25",
  "role": "user",
  "email": "wash@serenity.io",
  "email_domain": "serenity.io",
  "phone": "+1123456789",
  "name": "Hoban Washburn",
  "avatar": "https://example.org/128Wash.jpg",
  "owner_id": 127,
  "social_profiles": {
    "type": "list",
    "data": [
      {
        "type": "social_profile",
        "name": "Twitter",
        "url": "http://twitter.com/th1sland"
      }
    ]
  },
  "has_hard_bounced": false,
  "marked_email_as_spam": false,
  "unsubscribed_from_emails": false,
  "created_at": 1571672154,
  "updated_at": 1571672158,
  "signed_up_at": 1571069751,
  "last_seen_at": 1571069751,
  "last_replied_at": 1571672158,
  "last_contacted_at": 1571672158,
  "last_email_opened_at": 1571673478,
  "last_email_clicked_at": 1571676789,
  "language_override": null,
  "browser": "chrome",
  "browser_version": "77.0.3865.90",
  "browser_language": "en",
  "os": "OS X 10.14.6",
  "location": {
    "type": "location",
    "country": "Ireland",
    "region": "Dublin",
    "city": "Dublin",
    "country_code": "IRL",
    "continent_code": "EU"
  },
  "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": {
    "paid_subscriber": true,
    "monthly_spend": 155.5,
    "team_mates": 1
  },
  "tags": {
    "type": "list",
    "data": [
      {
        "type": "tag",
        "id": "2",
        "url": "/tags/2"
      },
      {
        "type": "tag",
        "id": "4",
        "url": "/tags/4"
      },
      {
        "type": "tag",
        "id": "5",
        "url": "/tags/5"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags",
    "total_count": 3,
    "has_more": false
  },
  "notes": {
    "type": "list",
    "data": [
      {
        "type": "note",
        "id": "20114858",
        "url": "/notes/20114858"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes",
    "total_count": 1,
    "has_more": false
  },
  "opted_out_subscription_types": {
    "type": "list",
    "data": [
      {
        "id": "1",
        "type": "subscription",
        "url": "/subscription_types/1"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions",
    "total_count": 1,
    "has_more": false
  },
  "companies": {
    "type": "list",
    "data": [
      {
        "type": "company",
        "id": "5ba686093d7cf93552a3dc99",
        "url": "/companies/5ba686093d7cf93552a3dc99"
      },
      {
        "type": "company",
        "id": "5cee64a03d7cf90c51b36f19",
        "url": "/companies/5cee64a03d7cf90c51b36f19"
      },
      {
        "type": "company",
        "id": "5d7668883d7cf944dbc5c791",
        "url": "/companies/5d7668883d7cf944dbc5c791"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies",
    "total_count": 3,
    "has_more": false
  },
  "utm_campaign": "my-campaign",
  "utm_content": null,
  "utm_medium": "social",
  "utm_source": null,
  "utm_term": null,
  "referrer": null
}

Contact Object Keys and Descriptions

Key	Type	Description
type	String	The type of object - `contact`.
id	String	The unique identifier for the contact which is given by Intercom.
workspace_id	String	The id of the workspace which the contact belongs to.
external_id	String	A unique identifier for the contact which is given to Intercom.
role	String	The role of the contact - `user` or `lead`.
email	String	The contact's email.
email_domain	String	The contact's email domain.
phone	String	The contact's phone.
name	String	The contact's name.
avatar	String	An image URL containing the avatar of a contact.
owner_id	Integer	The id of an admin that has been assigned account ownership of the contact.
social_profiles	List	A list of social profiles associated to 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	Date (UNIX timestamp)	The time when the contact was created.
updated_at	Date (UNIX timestamp)	The time when the contact was last updated.
signed_up_at	Date (UNIX timestamp)	The time specified for when a contact signed up.
last_seen_at	Date (UNIX timestamp)	The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
last_replied_at	Date (UNIX timestamp)	The time when the contact last messaged in.
last_contacted_at	Date (UNIX timestamp)	The time when the contact was last messaged.
last_email_opened_at	Date (UNIX timestamp)	The time when the contact last opened an email.
last_email_clicked_at	Date (UNIX timestamp)	The time when the contact last clicked a link in an email.
language_override	String	A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
browser	String	The name of the browser which the contact is using.
browser_version	String	The version of the browser which the contact is using.
browser_language	String	The language set by the browser which the contact is using.
os	String	The operating system which the contact is using.
location	Object	An object showing location details of the contact.
android_app_name	String	The name of the Android app which the contact is using.
android_app_version	String	The version of the Android app which the contact is using.
android_device	String	The Android device which the contact is using.
android_os_version	String	The version of the Android OS which the contact is using.
android_sdk_version	String	The version of the Android SDK which the contact is using.
android_last_seen_at	Date (UNIX timestamp)	The last time the contact used the Android app.
ios_app_name	String	The name of the iOS app which the contact is using.
ios_app_version	String	The version of the iOS app which the contact is using.
ios_device	String	The iOS device which the contact is using.
ios_os_version	String	The version of iOS which the contact is using.
ios_sdk_version	String	The version of the iOS SDK which the contact is using.
ios_last_seen_at	Date (UNIX timestamp)	The last time the contact used the iOS app.
custom_attributes	Object	The custom attributes which are set for the contact.
tags	Addressable List	The tags which have been added to the contact.
notes	Addressable List	The notes which have been added to the contact.
companies	Addressable List	The companies which the contact belongs to.
utm_campaign	String	Identifies a specific product promotion or strategic campaign
utm_content	String	Identifies what specifically was clicked to bring the user to the site
utm_medium	String	Identifies what type of link was used
utm_source	String	Identifies which site sent the traffic
utm_term	String	Identifies search terms
referrer	String	The URL of the page the contact was last on.

Location Object

Key	Type	Description
type	String	The type of object - `location`.
country	String	The country where the contact is.
region	String	A subdivision of the country which the contact is in (ie. state, province, county, territory, etc).
city	String	The city where the contact is.
country_code	String	The country code where the contact is.
continent_code	String	The continent code where the contact is.

Key	Type	Description
type	String	The type of object - `social_profile`.
name	String	The name of the service (ie. Twitter, Facebook, etc).
url	String	The profile page for the contact on the service.

Addressable List

Key	Type	Description
type	String	The type of object - `list`.
data	Array	An array of Addressable Objects. Maximum of 10.
url	String	The URL where the full list can be accessed (ie. `/contacts/1234/companies`).
total_count	Integer	The total amount of records.
has_more	Boolean	Whether there's more Addressable Objects to be viewed. If `true`, use the `url` to view all.

Addressable Object

Key	Type	Description
type	String	The type of object - `company`, `note`, `tag`.
id	String	The id of the object.
url	String	The URL where the object in question can be accessed (ie. `/companies/45678`).