Skip to content
Home/
REST API Reference
/
/
Retrieve a company by ID

Retrieve a company by ID

Request

You can fetch a single company.

Security
bearerAuth
Path
company_idstringrequired

The unique identifier for the company which is given by Intercom

Example:5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Query
typestring

Set to user or users to return the company's users instead of the company. The response is then a user.list object with a users array in the legacy user format.

Enum:"user""users"
Example:type=users
pageinteger

The page of users to fetch. Used only when type is user or users. Defaults to first page. There is a limit of 10,000 users; a page and per_page that go past it return a 400 error with code bad_request.

Example:page=1
per_pageinteger, <= 60

How many users to return per page. Used only when type is user or users. Defaults to 50. A value above 60 returns a 400 error with code parameter_invalid.

Example:per_page=50
Headers
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
curl -i -X GET \
  'https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632?type=users&page=1&per_page=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

Successful

Bodyapplication/json
One of:

Companies allow you to represent organizations using your product. Each company will have its own description and be associated with contacts. You can fetch, create, update and list companies.

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 &amp;.

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 &amp;.

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": "1",
  "id": "6762f07f1bb69f9f2193baf5",
  "app_id": "this_is_an_id159_that_should_be_at_least_",
  "name": "company1",
  "remote_created_at": 1734537343,
  "created_at": 1734537343,
  "updated_at": 1734537343,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 1,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {},
  "notes": {
    "type": "note.list",
    "data": [],
    "url": "/companies/6762f07f1bb69f9f2193baf5/notes",
    "total_count": 0,
    "has_more": false
  }
}