Create or Update a company

REST API Reference

Request

You can create or update a company.

Companies will be only visible in Intercom when there is at least one associated user.

Companies are looked up via company_id in a POST request, if not found via company_id, the new company will be created, if found, that company will be updated.

You must send either company_id or id. A request with neither returns a 400 error.

Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a 400 error.

Using `company_id`

You can set a unique company_id value when creating a company. However, it is not possible to update company_id. Be sure to set a unique value once upon creation of the company.

Requires the write_users_companies OAuth scope.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

Bodyapplication/json

namestring

The name of the Company. Leading and trailing whitespace is removed.

Example:"Intercom"

company_idstring

The company id you have defined for the company. Can't be updated

Example:"625e90fc55ab113b6d92175f"

idstring

An alternative name for company_id. Supply this or company_id.

Example:"625e90fc55ab113b6d92175f"

planstring

The name of the plan you have associated with the company.

Example:"Enterprise"

sizeinteger

The number of employees in this company.

Example:100

websitestring

The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.

Example:"https://www.example.com"

industrystring

The industry that this company operates in.

Example:"Manufacturing"

custom_attributesobject

Values for custom attributes that already exist in your workspace. Each value can be a string, integer, number, boolean or null. Arrays and objects aren't accepted.

Example:

{
  "paid_subscriber": true,
  "monthly_spend": 155.5,
  "team_mates": 9
}

remote_created_atinteger

The time the company was created by you.

Example:1394531169

update_last_request_atboolean

Set to true to update the company's last seen time to now.

Example:true

monthly_spendinteger

How much revenue the company generates for your business. Floats are truncated to whole integers, so 155.98 is stored as 155. A value above 2147483647 (2**31-1) is stored as 0. 2147483647 itself, or a value of -2147483648 or below, returns a 422 error.

Example:1000

curl -i -X POST \
  https://api.intercom.io/companies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "company_id": "company_remote_id",
    "name": "my company",
    "remote_created_at": 1374138000
  }'

Responses

Successful

Bodyapplication/json

typestring

Value is company

Value:"company"

Example:"company"

idstring

The Intercom defined id representing the company.

Example:"531ee472cce572a6ec000006"

namestring

The name of the company. Returned HTML-escaped, for example & as &.

Example:"Blue Sun"

app_idstring

The Intercom defined code of the workspace the company is associated to.

Example:"ecahpwf5"

planobject

company_idstring

The company id you have defined for the company. Returned HTML-escaped, for example & as &.

Example:"6"

remote_created_atinteger

The time the company was created by you.

Example:1663597223

created_atinteger

The time the company was added in Intercom.

Example:1663597223

updated_atinteger

The last time the company was updated.

Example:1663597223

last_request_atinteger

The time the company last recorded making a request.

Example:1663597223

sizeinteger

The number of employees in the company.

Example:100

websitestring

The URL for the company website.

Example:"https://www.intercom.com"

industrystring

The industry that the company operates in.

Example:"Software"

monthly_spendinteger

How much revenue the company generates for your business.

Example:100

session_countinteger

How many sessions the company has recorded.

Example:100

user_countinteger

The number of users in the company.

Example:100

custom_attributesobject

The custom attributes you have set on the company.

Example:

{
  "paid_subscriber": true,
  "monthly_spend": 155.5,
  "team_mates": 9
}

tagsobject

The list of tags associated with the company

segmentsobject

Always returned empty. Fetch a company's segments with the list attached segments endpoint.

notesobject

The list of notes associated with the company

Response

{
  "type": "company",
  "company_id": "company_remote_id",
  "id": "6762f0761bb69f9f2193bae2",
  "app_id": "this_is_an_id147_that_should_be_at_least_",
  "name": "my company",
  "remote_created_at": 1374138000,
  "created_at": 1734537334,
  "updated_at": 1734537334,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 0,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {
    "industry": "manufacturing"
  },
  "notes": {
    "type": "note.list",
    "data": [],
    "url": "/companies/6762f0761bb69f9f2193bae2/notes",
    "total_count": 0,
    "has_more": false
  }
}