API ReferenceBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

Create or Update User

Create or Update Users

$ curl https://api.intercom.io/users \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
  "user_id": "25",
  "email": "[email protected]",
  "name": "Hoban Washburne",
  "phone": "555671243",
  "signed_up_at": 1392731331,
  "custom_attributes": {
    "paid_subscriber" : true,
    "monthly_spend": 155.5,
    "team_mates": 9,
  "companies": [
      "company_id" : "366",
      "name" : "Serenity",
      "monthly_spend" : 500
HTTP/1.1 200 OK

    "type": "user",
    "id": "5714dd359a3fd47136000001",
    "user_id": "25",
    "anonymous": false,
    "email": "[email protected]",
    "phone": "555671243",
    "name": "Hoban Washburne",
    "pseudonym": null,
    "avatar": {
        "type": "avatar",
        "image_url": "https://secure.gravatar.com/avatar/0c3c17fd49f45c43f482730782b36d36?s=24&d=identicon"
    "app_id": "ja43hiec",
    "companies": {
        "type": "company.list",
        "companies": [
                "type": "company",
                "company_id": "366",
                "id": "574854e3ecd0c547ae0000e4",
                "name": "Serenity"
    "location_data": {
    "last_request_at": null,
    "last_seen_ip": null,
    "created_at": 1460985141,
    "remote_created_at": 1392731331,
    "signed_up_at": 1392731331,
    "updated_at": 1480075457,
    "session_count": 0,
    "social_profiles": {
        "type": "social_profile.list",
        "social_profiles": [
    "unsubscribed_from_emails": false,
    "user_agent_data": null,
    "tags": {
        "type": "tag.list",
        "tags": []
    "segments": {
        "type": "segment.list",
        "segments": []
    "custom_attributes": {
        "paid_subscriber": true,
        "monthly_spend": 155.5,
        "team_mates": 9,
        "last_order_at": 1475569818
intercom.users.create(:user_id => '25', :email => "[email protected]")
    "user_id" => "25",
    "email" => "[email protected]",
    "name" => "Hoban Washburne",
    "phone" => "555671243",
    "signed_up_at" => 1392731331,
    "last_seen_ip" => "",
    "last_seen_user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9",
    "custom_attributes" => [
        "paid_subscriber"  => true,
        "monthly_spend" => 155.5,
        "team_mates" => 9,
        "last_order_at" =>1475569818,
    "companies" => [
            "company_id"  => "366",
            "name"  => "Serenity",
            "monthly_spend"  => 500
import static io.intercom.api.CustomAttribute.*;

User user = new User()
.setEmail("[email protected]")
.addCustomAttribute(newStringAttribute("role", "sergeant"))
.addCustomAttribute(newBooleanAttribute("browncoat", true));

user = User.create(user);

Users can be created or updated via a POST method to https://api.intercom.io/users, which accepts a JSON object describing the user.

Users not found via email or user_id will be created, and those that are found will be updated.

Note that the following lookup order applies when updating users - id then user_id then email, and results in the following logic:

  • id is matched - the user_id and email will be updated if they are sent.
  • user_id match - the email will be updated, the id is not updated.
  • email match where no user_id set on the matching user - the user_id will be set to the value sent in the request, the id is not updated.
  • email match where there is a user_id set on the matching user - a new unique record with new id will be created if a new value for user_id is sent in the request.

Note that email values are downcased after they have been submitted to our API.


The table below shows the fields you can create or update for a user:

user_idRequired if no email is supplied.A unique string identifier for the user. It is required on creation if an email is not supplied.
emailRequired if no user_id is supplied.The user's email address. It is required on creation if a user_id is not supplied.
phonenoThe user's phone number.
idnoThe id may be used for user updates.
signed_up_atnoThe time the user signed up
namenoThe user's full name
custom_attributesnoA hash of key/value pairs containing any other data about the user you want Intercom to store.
companiesnoIdentifies the companies this user belongs to.
last_request_atnoA UNIX timestamp (in seconds) representing the date the user last visited your application.
unsubscribed_from_emailsnoA boolean value representing the users unsubscribed status. default value if not sent is false.
update_last_request_atnoA boolean value, which if true, instructs Intercom to update the users' lastrequest_at value to the current API service time in UTC. _default value if not sent is false.
new_sessionnoA boolean value, which if true, instructs Intercom to register the request as a session.

In particular, please note that location data and social profiles are computed by the server and can not be updated via the API.

Custom Attributes

The custom_attributes object allows you to send any information you wish about a user with the following restrictions

Field names must not contain Periods ('.') or Dollar ('$') characters:

  • Field names must be no longer than 190 characters.
  • Field values must be JSON Strings, Numbers or Booleans - Objects and Arrays will be rejected.
  • String field values must be no longer than 255 characters.
  • Maximum of 250 fields.


Custom attribute as date

You can send dates as custom attributes by sending a unix timestamp. If the name of your custom attribute ends with _at then we'll automatically treat it as a date, rather than a number. See here for more info


A created or updated user object.

New user objects will be provided with an id field - this value cannot be created or edited by clients. Social profiles, location data and avatars are processed asynchronously, and may require a subsequent call to fetch their details.