Sign in

v51

latestOpenAPI 3.0.1MITraw.githubusercontent.com2026-08-01150230854.3 KB
Contacts

Create contact

You can create a new contact (ie. user or lead).

post/contacts

Headers

Intercom-Version'1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14'

Intercom API version.</br>By default, it's equal to the version set in the app package.

Example:2.14

Request body

OR
OR

Example request

{
  "role": "user",
  "external_id": "625e90fc55ab113b6d92175f",
  "email": "jdoe@example.com",
  "phone": "+353871234567",
  "name": "John Doe",
  "avatar": "https://www.example.com/avatar_image.jpg",
  "signed_up_at": 1571672154,
  "last_seen_at": 1571672154,
  "owner_id": 123,
  "unsubscribed_from_emails": true,
  "custom_attributes": {
    "paid_subscriber": true,
    "monthly_spend": 155.5,
    "team_mates": 1
  }
}

Response

successful

typestring

The type of object.

idstring

The unique identifier for the contact which is given by Intercom.

external_idstring nullable

The unique identifier for the contact which is provided by the Client.

workspace_idstring

The id of the workspace which the contact belongs to.

rolestring

The role of the contact.

emailstring

The contact's email.

email_domainstring

The contact's email domain.

phonestring nullable

The contacts phone.

namestring nullable

The contacts name.

owner_idinteger nullable

The id of an admin that has been assigned account ownership of the contact.

has_hard_bouncedboolean

Whether the contact has had an email sent to them hard bounce.

marked_email_as_spamboolean

Whether the contact has marked an email sent to them as spam.

unsubscribed_from_emailsboolean

Whether the contact is unsubscribed from emails.

created_atinteger

(Unix timestamp in seconds) The time when the contact was created.

updated_atinteger

(Unix timestamp in seconds) The time when the contact was last updated.

signed_up_atinteger nullable

(Unix timestamp in seconds) The time specified for when a contact signed up.

last_seen_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).

last_replied_atinteger nullable

(Unix timestamp in seconds) The time when the contact last messaged in.

last_contacted_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last messaged.

last_email_opened_atinteger nullable

(Unix timestamp in seconds) The time when the contact last opened an email.

last_email_clicked_atinteger nullable

(Unix timestamp in seconds) The time when the contact last clicked a link in an email.

language_overridestring nullable

A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.

browserstring nullable

The name of the browser which the contact is using.

browser_versionstring nullable

The version of the browser which the contact is using.

browser_languagestring nullable

The language set by the browser which the contact is using.

osstring nullable

The operating system which the contact is using.

android_app_namestring nullable

The name of the Android app which the contact is using.

android_app_versionstring nullable

The version of the Android app which the contact is using.

android_devicestring nullable

The Android device which the contact is using.

android_os_versionstring nullable

The version of the Android OS which the contact is using.

android_sdk_versionstring nullable

The version of the Android SDK which the contact is using.

android_last_seen_atinteger nullable

(Unix timestamp in seconds) The time when the contact was last seen on an Android device.

ios_app_namestring nullable

The name of the iOS app which the contact is using.

ios_app_versionstring nullable

The version of the iOS app which the contact is using.

ios_devicestring nullable

The iOS device which the contact is using.

ios_os_versionstring nullable

The version of iOS which the contact is using.

ios_sdk_versionstring nullable

The version of the iOS SDK which the contact is using.

ios_last_seen_atinteger nullable

(Unix timestamp in seconds) The last time the contact used the iOS app.

custom_attributesobject

The custom attributes which are set for the contact.

Example response

{
  "type": "contact",
  "id": "5ba682d23d7cf92bef87bfd4",
  "external_id": "f3b87a2e09d514c6c2e79b9a",
  "workspace_id": "ecahpwf5",
  "role": "user",
  "email": "joe@example.com",
  "email_domain": "example.com",
  "phone": "+1123456789",
  "name": "John Doe",
  "owner_id": 123,
  "has_hard_bounced": true,
  "marked_email_as_spam": true,
  "unsubscribed_from_emails": true,
  "created_at": 1571672154,
  "updated_at": 1571672154,
  "signed_up_at": 1571672154,
  "last_seen_at": 1571672154,
  "last_replied_at": 1571672154,
  "last_contacted_at": 1571672154,
  "last_email_opened_at": 1571672154,
  "last_email_clicked_at": 1571672154,
  "language_override": "en",
  "browser": "Chrome",
  "browser_version": "80.0.3987.132",
  "browser_language": "en-US",
  "os": "Mac OS X",
  "android_app_name": "Intercom",
  "android_app_version": "5.0.0",
  "android_device": "Pixel 3",
  "android_os_version": "10",
  "android_sdk_version": "28",
  "android_last_seen_at": 1571672154,
  "ios_app_name": "Intercom",
  "ios_app_version": "5.0.0",
  "ios_device": "iPhone 11",
  "ios_os_version": "13.3.1",
  "ios_sdk_version": "13.3.1",
  "ios_last_seen_at": 1571672154,
  "avatar": {
    "type": "avatar",
    "image_url": "https://example.org/128Wash.jpg"
  },
  "tags": {
    "data": [
      {
        "type": "note",
        "id": "123",
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags",
    "total_count": 100,
    "has_more": true
  },
  "notes": {
    "data": [
      {
        "type": "note",
        "id": "123",
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes",
    "total_count": 100,
    "has_more": true
  },
  "companies": {
    "data": [
      {
        "id": "5ba682d23d7cf92bef87bfd4",
        "type": "company",
        "url": "/companies/5ba682d23d7cf92bef87bfd4"
      }
    ],
    "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies",
    "total_count": 100,
    "has_more": true
  },
  "location": {
    "type": "location",
    "country": "Ireland",
    "region": "Dublin",
    "city": "Dublin"
  },
  "social_profiles": {
    "data": [
      {
        "type": "social_profile",
        "name": "Facebook",
        "url": "http://twitter.com/th1sland"
      }
    ]
  }
}