Intercom API (unofficial showcase)
POST/contacts

Create a contact

Creates a new contact, such as a user or lead. Provide at least one of email, external_id, or role to identify the contact, and include email whenever you set email_verified. The response contains the created contact object.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 12 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Contact details and custom attributes for the new contact; provide at least one of email, external_id, or role.

rolestringoptional
The role of the contact.
external_idstringoptional
A unique identifier for the contact which is given to Intercom
email_verifiedbooleanoptional
Whether the contact has proved they own this email address, for example through a confirmation link or one-time code you sent. Send it together with `email`. `email_verified` without `email` is rejected. Changing a contact's email resets it to not verified. Intercom reuses leads with a verified email when an inbound email, conversation or ticket matches the address.
emailstringoptional
The contacts email
phonestringoptional
The contacts phone
namestringoptional
The contacts name
avatarstringoptional
An image URL containing the avatar of a contact
signed_up_atintegeroptional
(Unix timestamp in seconds) The time specified for when a contact signed up.
last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
owner_idstringoptional
The id of an admin that has been assigned account ownership of the contact
unsubscribed_from_emailsbooleanoptional
Whether the contact is unsubscribed from emails
custom_attributesobjectoptional
The custom attributes which are set for the contact

2 status codes
200Returns the created contact object, including its contact details and `enabled_push_messaging` value.
enabled_push_messagingbooleanoptional
If the user has enabled push messaging.
typestringoptional
The type of object.
idstringoptional
The unique identifier for the contact which is given by Intercom.
external_idstringoptional
The unique identifier for the contact which is provided by the Client.
workspace_idstringoptional
The id of the workspace which the contact belongs to.
rolestringoptional
The role of the contact.
emailstringoptional
The contact's email.
email_domainstringoptional
The contact's email domain.
email_verifiedbooleanoptional
Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead.
phonestringoptional
The contacts phone.
namestringoptional
The contacts name.
owner_idstringoptional
The id of an admin that has been assigned account ownership of the contact.
has_hard_bouncedbooleanoptional
Whether the contact has had an email sent to them hard bounce.
marked_email_as_spambooleanoptional
Whether the contact has marked an email sent to them as spam.
unsubscribed_from_emailsbooleanoptional
Whether the contact is unsubscribed from emails.
created_atintegeroptional
(Unix timestamp in seconds) The time when the contact was created.
updated_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last updated.
signed_up_atintegeroptional
(Unix timestamp in seconds) The time specified for when a contact signed up.
last_seen_atintegeroptional
(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_atintegeroptional
(Unix timestamp in seconds) The time when the contact last messaged in.
last_contacted_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last messaged.
last_email_opened_atintegeroptional
(Unix timestamp in seconds) The time when the contact last opened an email.
last_email_clicked_atintegeroptional
(Unix timestamp in seconds) The time when the contact last clicked a link in an email.
language_overridestringoptional
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
browserstringoptional
The name of the browser which the contact is using.
browser_versionstringoptional
The version of the browser which the contact is using.
browser_languagestringoptional
The language set by the browser which the contact is using.
osstringoptional
The operating system which the contact is using.
android_app_namestringoptional
The name of the Android app which the contact is using.
android_app_versionstringoptional
The version of the Android app which the contact is using.
android_devicestringoptional
The Android device which the contact is using.
android_os_versionstringoptional
The version of the Android OS which the contact is using.
android_sdk_versionstringoptional
The version of the Android SDK which the contact is using.
android_last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen on an Android device.
ios_app_namestringoptional
The name of the iOS app which the contact is using.
ios_app_versionstringoptional
The version of the iOS app which the contact is using.
ios_devicestringoptional
The iOS device which the contact is using.
ios_os_versionstringoptional
The version of iOS which the contact is using.
ios_sdk_versionstringoptional
The version of the iOS SDK which the contact is using.
ios_last_seen_atintegeroptional
(Unix timestamp in seconds) The last time the contact used the iOS app.
custom_attributesobjectoptional
The custom attributes which are set for the contact.
avatarobjectoptional
tagsobjectoptional
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
notesobjectoptional
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
companiesobjectoptional
An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.
locationobjectoptional
An object containing location meta data about a Intercom contact.
social_profilesobjectoptional
An object containing social profiles that a contact has.
merge_historyarray<MergeHistoryItem>optional
A list of contacts that were merged into this contact. Only included in the response when `include_merge_history=true` is passed as a query parameter. Only available for contacts with a `user` role.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized. Provide at least one of email, external_id, or role; if you set email_verified, include email in the request body.