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

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#

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"
}