Icon

Intercom (version v1.*.*)

add_customer_to_conversation

Parameters

conversation_id (required)

Conversation ID

Type: string

$body

Type: object

{
"user_id" : "string",
"admin_id" : "string",
"intercom_user_id" : "string",
"email" : "string",
"customer" : {
"user_id" : "string",
"intercom_user_id" : "string",
"email" : "string"
}
}

archive_user

Archive a user. The archive action will not perform a 'hard' delete. If you want to permanently delete your user then you will need to use the permanent delete API.

Parameters

email

The email you have defined for the user

Type: string

user_id

The user id you have defined for the user

Type: string

convert_lead

Leads can be converted to Users. This is done by passing both Lead and User identifiers. If the User exists, then the Lead will be merged into it, the Lead deleted and the User returned. If the User does not exist, the Lead will be converted to a User, with the User identifiers replacing it's Lead identifiers.

Parameters

$body

Type: object

{
"contact" : {
"last_request_at" : "The time the Lead last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time the Lead was added to Intercom",
"avatar" : { },
"type" : "string",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the lead was last on",
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"unsubscribed_from_emails" : "Whether the Lead is unsubscribed from emails",
"updated_at" : "The last time the Lead was updated",
"user_id" : "Automatically generated identifier for the Lead",
"phone" : "The phone number you have defined for the lead",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"name" : "The name of the Lead",
"id" : "The Intercom defined id representing the Lead",
"email" : "The email you have defined for the Lead",
"utm_source" : "Identifies which site sent the traffic",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site"
},
"user" : {
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
}
}

convert_visitor

Visitors can be converted to Users. This is done by passing both Visitor and User identifiers and a type attribute set to 'user'. If the User exists, then the Visitor will be merged into it, the Visitor deleted and the User returned. If the User does not exist, the Visitor will be converted to a User, with the User identifiers replacing its Visitor identifiers. Visitors can be converted to Leads. This is done by passing Visitor identifiers and a type attribute set to 'lead'.

Parameters

$body

Type: object

{
"visitor" : {
"last_request_at" : "The time the Lead last recorded making a request",
"created_at" : "The time the Visitor was added to Intercom",
"avatar" : {
"image_url" : "An avatar image URL. note: the image url needs to be https.",
"type" : "string"
},
"type" : "string",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"unsubscribed_from_emails" : "Whether the Visitor is unsubscribed from emails",
"updated_at" : "The last time the Visitor was updated",
"user_id" : "Automatically generated identifier for the Visitor",
"location_data" : {
"image_url" : "An avatar image URL. note: the image url needs to be https.",
"type" : "string"
},
"name" : "The name of the Visitor",
"id" : "The Intercom defined id representing the Visitor"
},
"type" : "string. Possible values: user | lead",
"user" : {
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
}
}

create_company

Create or update a company. Companies are looked up via company_id. If not found via company_id, the new company will be created. If found, that company will be updated.

Parameters

$body

Type: object

{
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
}

create_event

Create an event.

Parameters

$body

Type: object

{
"metadata" : "optional metadata about the event.",
"user_id" : "Your identifier for the user.",
"event_name" : "The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example `updated-plan`.",
"created_at" : "The time the event occurred as a UTC Unix timestamp",
"id" : "Your identifier for a lead or a user.",
"email" : "An email address for your user. An email should only be used where your application uses email to uniquely identify users"
}

create_lead

Create or update a lead

Parameters

$body

Type: object

{
"last_request_at" : "The time the Lead last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time the Lead was added to Intercom",
"avatar" : { },
"type" : "string",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the lead was last on",
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"unsubscribed_from_emails" : "Whether the Lead is unsubscribed from emails",
"updated_at" : "The last time the Lead was updated",
"user_id" : "Automatically generated identifier for the Lead",
"phone" : "The phone number you have defined for the lead",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"name" : "The name of the Lead",
"id" : "The Intercom defined id representing the Lead",
"email" : "The email you have defined for the Lead",
"utm_source" : "Identifies which site sent the traffic",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site"
}

create_note

Create a note.

Parameters

$body

Type: object

{
"author" : {
"team_ids" : [ "string" ],
"name" : "The name of the admin",
"away_mode_enabled" : "Identifies if this admin is currently set in away mode.",
"away_mode_reassign" : "Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.",
"id" : "The id of the admin",
"avatar" : "Image for the associated team or teammate",
"type" : "string",
"has_inbox_seat" : "Identifies if a teammate has a paid inbox seat to restrict/allow features that require them",
"job_title" : "The job title of the admin",
"email" : "The email address of the admin"
},
"created_at" : "The time the note was created",
"id" : "The id representing the note",
"type" : "string",
"body" : "The body text of the note.",
"user" : {
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
}
}

create_tag

Create a tag by sending a tag object with a name. The tag name may contain whitespace and punctuation.
If the same tag name is sent multiple times, only one tag will be created for that name - this lets you avoid checking if a tag exists first.
Tag names are case insensitive - 'MyTag' and 'mytag' will result in a single tag being created.
Update a tag by submitting a tag object with the id of the tag to update and a new name for the tag. A successful request will update the name value for that tag and return the updated tag in the response.
Users can be tagged by supplying a users array. The array contains objects identifying users by their id, email or user_id fields.
Companies can be tagged by sending a companies array. The array contains objects identifying companies by their id or company_id fields.
Contacts/Leads can be tagged by supplying a users array. The array contains objects identifying leads by their id fields.
Companies and user tag directives cannot be mixed in the same request - a request will not process both company and user arrays.
We recommend tagging no more than 50 users at a time as larger amounts could result in a timeout.
To untag a company or user, each user or company object sent in the tagging request can be submitted with an untag field whose value is set to true.
Objects submitted with an untag field can be mixed with other objects being tagged. This allows tag and untag operations to be performed in a single request.

Parameters

$body

Type: object

{
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
}

create_update_user

Create a new user or update an existing user.

Parameters

$body

Type: object

{
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
}

create_user

Create a new user or update an existing user.

Parameters

$body

Type: object

{
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
}

delete_company

Delete a company

Parameters

user_id

User ID

Type: string

delete_company_by_id

Delete a company

Parameters

id (required)

Company ID

Type: string

delete_customer_to_conversation

Parameters

conversation_id (required)

Conversation ID

Type: string

id (required)

Customer ID

Type: string

delete_lead

Delete a lead

Parameters

user_id

User ID

Type: string

delete_lead_by_id

Delete a lead

Parameters

id (required)

Lead ID

Type: string

delete_tag

Delete a tag

Parameters

id (required)

Tag ID

Type: string

delete_visitor

Delete a visitor

Parameters

user_id

User ID

Type: string

delete_visitor_by_id

Delete a visitor

Parameters

id (required)

Visitor ID

Type: string

find_user

Find an individual user or many users.

Parameters

email

The email you have defined for the user

Type: string

user_id

The user id you have defined for the user

Type: string

get_admin

Get a particular admin

Parameters

id (required)

Admin ID

Type: string

get_company

Get a company

Parameters

id (required)

Company ID

Type: string

get_conversation

Get a single conversation.

Parameters

id (required)

Conversation ID

Type: string

display_as

Set to plaintext to retrieve conversation messages in plain text

Type: string

get_count

Parameters

count

Type: number

type

Type: string

get_current_admin_and_app

This operation has no parameters

get_lead

Get a lead

Parameters

id (required)

Lead ID

Type: string

get_note

Get a note.

Parameters

id (required)

Note ID

Type: string

get_segment

Get a segment for an App.

Parameters

id (required)

Segment ID

Type: string

include_count

include counts in your segment model in the response

Type: boolean

get_team

Get a particular team

Parameters

id (required)

Team ID

Type: string

get_user

Get a user

Parameters

id (required)

System-assigned user ID

Type: string

get_visitor

Get a visitor

Parameters

id (required)

Visitor ID

Type: string

list_activity_logs_for_admin

Get a log of activities by all admins in an app.

Parameters

created_at_after (required)

The start date that you request data for. It must be formatted as a UNIX timestamp.

Type: string

created_at_before

The end date that you request data for. It must be formatted as a UNIX timestamp.

Type: string

resultsPath

Type: STRING

list_admins

List an App's admins.

Parameters

resultsPath

Type: STRING

list_companies

List Companies (or list users for company)

Parameters

company_id

Company ID

Type: string

name

Company name

Type: string

order

Type: string

Potential values: asc, desc

resultsPath

Type: STRING

segment_id

Type: number

tag_id

Type: number

type

Type: string

list_conversations

List conversations

Parameters

admin_id

The id for the Admin whose conversations to retrieve. To retrieve all unassigned conversations, set the id to be 'nobody'.

Type: string

display_as

Set to plaintext to retrieve conversation messages in plain text

Type: string

email

Type: string

intercom_user_id

Type: string

open

when true fetches just open conversations, when false just closed conversations

Type: boolean

order

Type: string

Potential values: asc, desc

resultsPath

Type: STRING

sort

Type: string

Potential values: created_at, updated_at, waiting_since

type

The type of entity to query for.

Type: string

Potential values: admin, user

unread

when true fetches just unread conversations

Type: boolean

user_id

Type: string

list_data_attributes_for_companies

List all the company data attributes for your app.

Parameters

include_archived

Include archived attributes in the list. By default only non-archived data attributes are returned.

Type: boolean

list_data_attributes_for_customers

List all data attributes for customers. Customer attributes describe attributes belonging to users, leads and visitors. All 3 models have the same data attributes.

Parameters

include_archived

Include archived attributes in the list. By default only non-archived data attributes are returned.

Type: boolean

list_events_for_user

List events for a user

Parameters

type (required)

Type: string

email

Type: string

intercom_user_id

Type: string

resultsPath

Type: STRING

summary

When set to true, event counts are returned grouped by event name.

Type: boolean

user_id

Type: string

list_leads

List Leads

Parameters

email

Email address

Type: string

phone

Phone number

Type: string

resultsPath

Type: STRING

user_id

User ID

Type: string

list_notes_for_user

List notes for a user

Parameters

email

Type: string

id

Type: string

resultsPath

Type: STRING

user_id

Type: string

list_segments

Get a list of segments for an App.

Parameters

include_count

include counts in your segment model in the response

Type: boolean

resultsPath

Type: STRING

type

if "company", list company segments, otherwise list user segments.

Type: string

list_tags

This operation has no parameters

list_teams

Get a list of teams for an App.

Parameters

resultsPath

Type: STRING

list_users

Find an individual user or many users.

Parameters

created_since

Limits results to users that were created in that last number of days.

Type: number

order

Returns the users in ascending or descending order.

Type: string

Potential values: asc, desc

resultsPath

Type: STRING

sort

What field to sort the results by.

Type: string

Potential values: created_at, last_request_at, signed_up_at, updated_at

list_users_for_company

List users for a company

Parameters

id (required)

Company ID

Type: string

resultsPath

Type: STRING

mark_conversation_as_read

Mark a conversation within Intercom as read.

Parameters

id (required)

Conversation ID

Type: string

$body

Type: object

{
"read" : "boolean"
}

post_message

Parameters

$body

Type: object

{
"template" : "The style of the outgoing message. Only valid for email messages. Possible values plain or personal.",
"subject" : "Optional unless message_type is email. The title of the email.",
"message_type" : "The kind of message being created.",
"from" : {
"team_ids" : [ "string" ],
"name" : "The name of the admin",
"away_mode_enabled" : "Identifies if this admin is currently set in away mode.",
"away_mode_reassign" : "Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.",
"id" : "The id of the admin",
"avatar" : "Image for the associated team or teammate",
"type" : "string",
"has_inbox_seat" : "Identifies if a teammate has a paid inbox seat to restrict/allow features that require them",
"job_title" : "The job title of the admin",
"email" : "The email address of the admin"
},
"to" : {
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time (in seconds) the user was added to Intercom",
"type" : "Value is 'user' or 'contact'",
"pseudonym" : "The pseudonym used if this user was previously a Lead (http://docs.intercom.io/Intercom-for-customer-communication/the-intercom-messenger)",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"unsubscribed_from_emails" : "Whether the user is unsubscribed from emails",
"updated_at" : "The last time the user was updated",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"id" : "The Intercom defined id representing the user",
"email" : "The email you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site",
"signed_up_at" : "The time (in seconds) the user signed up",
"last_request_at" : "The time the user last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"avatar" : { },
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the user was last on",
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"user_id" : "The user id you have defined for the user. (Max limit of 255 UTF-8 characters, and should not have trailing or leading spaces)",
"phone" : "The phone number of the user",
"session_count" : "How many sessions the user has recorded",
"name" : "The full name of the user",
"anonymous" : "Whether or not this is a Lead. Always false",
"utm_source" : "Identifies which site sent the traffic"
},
"body" : "The content of the message. HTML or plaintext."
}

post_reply

Parameters

conversation_id (required)

Conversation ID

Type: string

$body

Type: object

{
"attachment_urls" : [ "string" ],
"user_id" : "string",
"admin_id" : "string",
"message_type" : "string. Possible values: comment | assignment | open | close | note",
"intercom_user_id" : "string",
"type" : "string. Possible values: user | admin",
"body" : "The text body of the comment",
"email" : "string",
"snooze_until" : "The time in Unix time (i.e. seconds) you want the conversation to reopen",
"assignee_id" : "string"
}

post_reply_to_last_conversation

Parameters

$body

Type: object

{
"attachment_urls" : [ "string" ],
"user_id" : "string",
"admin_id" : "string",
"message_type" : "string. Possible values: comment | assignment | open | close | note",
"intercom_user_id" : "string",
"type" : "string. Possible values: user | admin",
"body" : "The text body of the comment",
"email" : "string",
"snooze_until" : "The time in Unix time (i.e. seconds) you want the conversation to reopen",
"assignee_id" : "string"
}

scroll_companies

Scroll over all companies. The List Companies
functionality does not work well for huge datasets, and can result in errors
and performance problems when paging deeply. The Scroll API provides an efficient
mechanism for iterating over all users in a dataset. Each app can only
have 1 scroll open at a time. You''ll get an error message if you try to have
more than one open per app. If the scroll isn''t used for 1 minute, it
expires and calls with that scroll param will fail. If the end of the scroll
is reached, "companies" will be empty and the scroll parameter will expire. Since scroll is often used on large datasets network errors such as
timeouts can be encountered. When this occurs you will need to restart your
scroll query as it is not possible to continue from a specific point when
using scroll.When this occurs you will see a HTTP 500 error with the following
message: “Request failed due to an internal network error. Please restart
the scroll operation.”

Parameters

scroll

scroll parameter

Type: string

scroll_leads

Scroll over all leads. The List Leads
functionality does not work well for huge datasets, and can result in errors
and performance problems when paging deeply. The Scroll API provides an efficient
mechanism for iterating over all users in a dataset. Each app can only
have 1 scroll open at a time. You''ll get an error message if you try to have
more than one open per app. If the scroll isn''t used for 1 minute, it
expires and calls with that scroll param will fail. If the end of the scroll
is reached, "leads" will be empty and the scroll parameter will expire. Since scroll is often used on large datasets network errors such as
timeouts can be encountered. When this occurs you will need to restart your
scroll query as it is not possible to continue from a specific point when
using scroll.When this occurs you will see a HTTP 500 error with the following
message: “Request failed due to an internal network error. Please restart
the scroll operation.”

Parameters

scroll

scroll parameter

Type: string

scroll_users

Scroll over all users. The List Users
functionality does not work well for huge datasets, and can result in errors
and performance problems when paging deeply. The Scroll API provides an efficient
mechanism for iterating over all users in a dataset. Each app can only
have 1 scroll open at a time. You''ll get an error message if you try to have
more than one open per app. If the scroll isn''t used for 1 minute, it
expires and calls with that scroll param will fail. If the end of the scroll
is reached, "users" will be empty and the scroll parameter will expire. Since scroll is often used on large datasets network errors such as
timeouts can be encountered. When this occurs you will need to restart your
scroll query as it is not possible to continue from a specific point when
using scroll.When this occurs you will see a HTTP 500 error with the following
message: “Request failed due to an internal network error. Please restart
the scroll operation.”

Parameters

scroll

scroll parameter

Type: string

set_admin_away

If you want to set an admin in away mode you can do this via a PUT request. You can also choose whether you want conversation replies to be automatically reassigned to your default inbox if you like.

Parameters

id (required)

Admin ID

Type: string

away_mode_enabled

Set to 'true' to change the status of the admin to away.

Type: boolean

away_mode_reassign

Set to 'true' to assign any new conversation replies to your default inbox.

Type: boolean

update_company

Create or update a company. Companies are looked up via company_id. If not found via company_id, the new company will be created. If found, that company will be updated.

Parameters

$body

Type: object

{
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
}

update_lead

Create or update a lead

Parameters

$body

Type: object

{
"last_request_at" : "The time the Lead last recorded making a request",
"utm_campaign" : "Identifies a specific product promotion or strategic campaign",
"utm_medium" : "Identifies what type of link was used",
"created_at" : "The time the Lead was added to Intercom",
"avatar" : { },
"type" : "string",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"utm_term" : "Identifies search terms",
"referrer" : "The URL of the page the lead was last on",
"companies" : [ {
"website" : "The URL for the company website",
"company_id" : "The company id you have defined for the company",
"last_request_at" : "The time the company last recorded making a request",
"created_at" : "The time the company was added to Intercom",
"industry" : "The industry that the company operates in",
"type" : "string",
"custom_attributes" : { },
"monthly_spend" : "How much revenue the company generates for your business",
"updated_at" : "The last time the company was updated",
"user_count" : "The number of users in the company",
"size" : "The number of employees in the company",
"session_count" : "How many sessions the company has recorded",
"name" : "The name of the company",
"id" : "The Intercom defined id representing the company",
"remote_created_at" : "The time the company was created by you",
"plan*" : "The name of the plan you have associated with the company."
} ],
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"unsubscribed_from_emails" : "Whether the Lead is unsubscribed from emails",
"updated_at" : "The last time the Lead was updated",
"user_id" : "Automatically generated identifier for the Lead",
"phone" : "The phone number you have defined for the lead",
"location_data" : {
"country_code" : "Optional. An ISO 3166 country code",
"city_name" : "Optional. A city name",
"timezone" : "Optional. An ISO 8601 timezone",
"latitude" : "Optional. The latitude",
"country_name" : "Optional. The country name",
"continent_code" : "Optional. A continent code",
"region_name" : "Optional. A region name",
"type" : "string",
"postal_code" : "Optional. A postal code",
"longitude" : "Optional. The longitude"
},
"name" : "The name of the Lead",
"id" : "The Intercom defined id representing the Lead",
"email" : "The email you have defined for the Lead",
"utm_source" : "Identifies which site sent the traffic",
"utm_content" : "Identifies what specifically was clicked to bring the user to the site"
}

update_tag

Create a tag by sending a tag object with a name. The tag name may contain whitespace and punctuation.
If the same tag name is sent multiple times, only one tag will be created for that name - this lets you avoid checking if a tag exists first.
Tag names are case insensitive - 'MyTag' and 'mytag' will result in a single tag being created.
Update a tag by submitting a tag object with the id of the tag to update and a new name for the tag. A successful request will update the name value for that tag and return the updated tag in the response.
Users can be tagged by supplying a users array. The array contains objects identifying users by their id, email or user_id fields.
Companies can be tagged by sending a companies array. The array contains objects identifying companies by their id or company_id fields.
Contacts/Leads can be tagged by supplying a users array. The array contains objects identifying leads by their id fields.
Companies and user tag directives cannot be mixed in the same request - a request will not process both company and user arrays.
We recommend tagging no more than 50 users at a time as larger amounts could result in a timeout.
To untag a company or user, each user or company object sent in the tagging request can be submitted with an untag field whose value is set to true.
Objects submitted with an untag field can be mixed with other objects being tagged. This allows tag and untag operations to be performed in a single request.

Parameters

$body

Type: object

{
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
}

update_visitor

Update a visitor. Passing identifiers (user_id or id) in the body will result in an update of an existing Visitor.

Parameters

$body

Type: object

{
"last_request_at" : "The time the Lead last recorded making a request",
"created_at" : "The time the Visitor was added to Intercom",
"avatar" : {
"image_url" : "An avatar image URL. note: the image url needs to be https.",
"type" : "string"
},
"type" : "string",
"custom_attributes" : { },
"segments" : [ {
"updated_at" : "The time the segment was updated",
"person_type" : "Type of the record: user or lead.",
"name" : "The name of the segment",
"count" : "The number of items in the user segment. It's returned when `include_count=true` is included in the request.",
"created_at" : "The time the segment was created",
"id" : "The id representing the segment",
"type" : "string"
} ],
"tags" : [ {
"name" : "The name of the tag",
"id" : "The id of the tag",
"type" : "string"
} ],
"social_profiles" : [ {
"name" : "The name of the service (e.g., twitter, facebook)",
"id" : "Optional. User ID on the service",
"type" : "string",
"url" : "The user homepage on the service",
"username" : "User name or handle on the service"
} ],
"unsubscribed_from_emails" : "Whether the Visitor is unsubscribed from emails",
"updated_at" : "The last time the Visitor was updated",
"user_id" : "Automatically generated identifier for the Visitor",
"location_data" : {
"image_url" : "An avatar image URL. note: the image url needs to be https.",
"type" : "string"
},
"name" : "The name of the Visitor",
"id" : "The Intercom defined id representing the Visitor"
}