Create or Update Company

Example Request

$ curl https://api.intercom.io/companies \\\n-X POST \\\n-H 'Authorization:Bearer <Your access token>' \\\n-H 'Accept: application/json' \\\n-H 'Content-Type:application/json' -d '\n{\n  \"name\": \"Blue Sun\",\n  \"plan\": \"Paid\",\n  \"company_id\": \"6\",\n  \"remote_created_at\": 1394531169,\n  \"size\": 750,\n  \"website\": \"http://www.example.com\",\n  \"industry\": \"Manufacturing\",\n  \"custom_attributes\": {\n    \"paid_subscriber\" : true,\n    \"team_mates\": 0,\n    \"monthly_spend\": 155.98\n  }\n}'
HTTP/1.1 200 OK\n\n{\n    \"type\": \"company\",\n    \"company_id\": \"6\",\n    \"id\": \"57e0120926806ceca3c13ba8\",\n    \"app_id\": \"pi3243fa\",\n    \"name\": \"Blue Sun\",\n    \"remote_created_at\": 1394531169,\n    \"created_at\": 1474302473,\n    \"updated_at\": 1475659931,\n    \"last_request_at\": 1473419085,\n    \"monthly_spend\": 49,\n    \"session_count\": 0,\n    \"user_count\": 0,\n    \"tags\": {\n        \"type\": \"tag.list\",\n        \"tags\": []\n    },\n    \"segments\": {\n        \"type\": \"segment.list\",\n        \"segments\": [\n            {\n                \"type\": \"segment\",\n                \"id\": \"56cc69cc8618d37b45000009\"\n            }\n        ]\n    },\n    \"plan\": {\n        \"type\": \"plan\",\n        \"id\": \"108609\",\n        \"name\": \"Paid\"\n    },\n    \"custom_attributes\": {\n        \"paid_subscriber\": true,\n        \"team_mates\": 0,\n        \"referral_source\": \"Google\",\n        \"founded\": \"20th Century\",\n        \"monthly_spend\": 155.98,\n        \"remove\": true\n    }\n}

Companies can be created or updated via a POST to https://api.intercom.io/companies, which accepts a JSON object describing the company.

Companies with no users

It is important to note that companies will be only visible in Intercom when there is at least one associated user. Check the Companies and Users section for more information

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.

Note that the company_id field itself cannot be updated through the API.

Companies may also be created or updated via a User request - see the section "Create or Update User".

Attributes

The table below shows the fields you can create or update for a company -

AttributeTypeDescription
remote_created_attimestampThe time the company was created by you
company_idstringThe company id you have defined for the company
namestringThe name of the company
monthly_spendnumberHow 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.
planstringThe name of the plan you have associated with the company
sizenumberThe number of employees in this company
websitestringThe URL for this company's website. Please note that the value specified here is not validated. Accepts any string.
industrystringThe industry that this company operates in
custom_attributesobjectA hash of key/value pairs containing any other data about the company you want Intercom to store.

Custom Attributes

The custom_attributes object allows you to send any information you wish about a company 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 100 fields.

Session Count

A company's session count is tied to users' session count whilst in the context of that company. So, to update a company session count,
update the user with that company and increment the user's session.

Returns

The created or updated company object.

New company objects will be provided with an id field - this value cannot be created or edited by clients.