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

KeyTypeDescription
typeStringThe type of object - contact.
idStringThe unique identifier for the contact which is given by Intercom.
workspace_idStringThe id of the workspace which the contact belongs to.
external_idStringA unique identifier for the contact which is given to Intercom.
roleStringThe role of the contact - user or lead.
emailStringThe contact's email.
email_domainStringThe contact's email domain.
phoneStringThe contact's phone.
nameStringThe contact's name.
avatarStringAn image URL containing the avatar of a contact.
owner_idIntegerThe id of an admin that has been assigned account ownership of the contact.
social_profilesListA list of social profiles associated to the contact.
has_hard_bouncedBooleanWhether the contact has had an email sent to them hard bounce.
marked_email_as_spamBooleanWhether the contact has marked an email sent to them as spam.
unsubscribed_from_emailsBooleanWhether the contact is unsubscribed from emails.
created_atDate (UNIX timestamp)The time when the contact was created.
updated_atDate (UNIX timestamp)The time when the contact was last updated.
signed_up_atDate (UNIX timestamp)The time specified for when a contact signed up.
last_seen_atDate (UNIX timestamp)The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
last_replied_atDate (UNIX timestamp)The time when the contact last messaged in.
last_contacted_atDate (UNIX timestamp)The time when the contact was last messaged.
last_email_opened_atDate (UNIX timestamp)The time when the contact last opened an email.
last_email_clicked_atDate (UNIX timestamp)The time when the contact last clicked a link in an email.
language_overrideStringA preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
browserStringThe name of the browser which the contact is using.
browser_versionStringThe version of the browser which the contact is using.
browser_languageStringThe language set by the browser which the contact is using.
osStringThe operating system which the contact is using.
locationObjectAn object showing location details of the contact.
android_app_nameStringThe name of the Android app which the contact is using.
android_app_versionStringThe version of the Android app which the contact is using.
android_deviceStringThe Android device which the contact is using.
android_os_versionStringThe version of the Android OS which the contact is using.
android_sdk_versionStringThe version of the Android SDK which the contact is using.
android_last_seen_atDate (UNIX timestamp)The last time the contact used the Android app.
ios_app_nameStringThe name of the iOS app which the contact is using.
ios_app_versionStringThe version of the iOS app which the contact is using.
ios_deviceStringThe iOS device which the contact is using.
ios_os_versionStringThe version of iOS which the contact is using.
ios_sdk_versionStringThe version of the iOS SDK which the contact is using.
ios_last_seen_atDate (UNIX timestamp)The last time the contact used the iOS app.
custom_attributesObjectThe custom attributes which are set for the contact.
tagsAddressable ListThe tags which have been added to the contact.
notesAddressable ListThe notes which have been added to the contact.
companiesAddressable ListThe companies which the contact belongs to.
utm_campaignStringIdentifies a specific product promotion or strategic campaign
utm_contentStringIdentifies what specifically was clicked to bring the user to the site
utm_mediumStringIdentifies what type of link was used
utm_sourceStringIdentifies which site sent the traffic
utm_termStringIdentifies search terms
referrerStringThe URL of the page the contact was last on.

Location Object

KeyTypeDescription
typeStringThe type of object - location.
countryStringThe country where the contact is.
regionStringA subdivision of the country which the contact is in (ie. state, province, county, territory, etc).
cityStringThe city where the contact is.
country_codeStringThe country code where the contact is.
continent_codeStringThe continent code where the contact is.

Social Profile Object

KeyTypeDescription
typeStringThe type of object - social_profile.
nameStringThe name of the service (ie. Twitter, Facebook, etc).
urlStringThe profile page for the contact on the service.

Addressable List

KeyTypeDescription
typeStringThe type of object - list.
dataArrayAn array of Addressable Objects. Maximum of 10.
urlStringThe URL where the full list can be accessed (ie. /contacts/1234/companies).
total_countIntegerThe total amount of records.
has_moreBooleanWhether there's more Addressable Objects to be viewed. If true, use the url to view all.

Addressable Object

KeyTypeDescription
typeStringThe type of object - company, note, tag.
idStringThe id of the object.
urlStringThe URL where the object in question can be accessed (ie. /companies/45678).