Intercom API (unofficial showcase)
POST/companies

Create or update a company

Creates a company or updates the existing company identified by company_id. Set a unique company_id when creating a company because it cannot be changed later; a company appears in Intercom only when it has at least one associated user.

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

1 parameter · 10 body fields
Intercom-Versionstringoptional
Selects the API version. Defaults to `2.17` when omitted; supported versions include 1.0 through 1.4 and 2.0 through 2.6.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Company details to create or update. If company_id matches an existing company, that company is updated; otherwise, a company is created.

namestringoptional
The name of the Company
company_idstringoptional
The company id you have defined for the company. Can't be updated
planstringoptional
The name of the plan you have associated with the company.
sizeintegeroptional
The number of employees in this company.
websitestringoptional
The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.
industrystringoptional
The industry that this company operates in.
custom_attributesobjectoptional
A hash of key/value pairs containing any other data about the company you want Intercom to store.
remote_created_atintegeroptional
The time the company was created by you.
update_last_request_atbooleanoptional
Set to true to update the company's last seen time to now.
monthly_spendintegeroptional
How much revenue the company generates for your business. Note that this will truncate floats. i.e. it only allow for whole integers, 155.98 will be truncated to 155. Note that this has an upper limit of 2**31-1 or 2147483647..

3 status codes
200Returns the company object, including its Intercom ID, name, company ID, plan, website, industry, spend, and timestamps.
typestringoptional
Value is `company`
Allowed:company
idstringoptional
The Intercom defined id representing the company.
namestringoptional
The name of the company.
app_idstringoptional
The Intercom defined code of the workspace the company is associated to.
planobjectoptional
company_idstringoptional
The company id you have defined for the company.
remote_created_atintegeroptional
The time the company was created by you.
created_atintegeroptional
The time the company was added in Intercom.
updated_atintegeroptional
The last time the company was updated.
last_request_atintegeroptional
The time the company last recorded making a request.
sizeintegeroptional
The number of employees in the company.
websitestringoptional
The URL for the company website.
industrystringoptional
The industry that the company operates in.
monthly_spendintegeroptional
How much revenue the company generates for your business.
session_countintegeroptional
How many sessions the company has recorded.
user_countintegeroptional
The number of users in the company.
custom_attributesobjectoptional
The custom attributes you have set on the company.
tagsobjectoptional
The list of tags associated with the company
segmentsobjectoptional
The list of segments associated with the company
notesobjectoptional
The list of notes associated with the company
400Returned when the request is invalid.

One documented failure

  • bad_request

    bad 'test' parameter

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

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

Error handling

A 400 is returned when the request is invalid. A 401 is returned when the request is unauthorized. When creating a company, company_id must be unique and cannot be changed after creation.