---
title: "Retrieve companies"
method: GET
path: "/companies"
tags: ["Companies"]
---

# Retrieve companies

`GET /companies`

You can fetch a single company by passing in `company_id` or `name`.

  `https://api.intercom.io/companies?name={name}`

  `https://api.intercom.io/companies?company_id={company_id}`

You can fetch all companies and filter by `segment_id` or `tag_id` as a query parameter.

  `https://api.intercom.io/companies?tag_id={tag_id}`

  `https://api.intercom.io/companies?segment_id={segment_id}`

## Query parameters

- `name` string
- `company_id` string
- `tag_id` string
- `segment_id` string
- `page` integer
- `per_page` integer

## Headers

- `Intercom-Version` '1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14' — Intercom API version.</br>By default, it's equal to the version set in the app package.

## Response `200`

Successful

- CompanyList — This will return a list of companies for the App.
  - `type` 'list' — The type of object - `list`.
  - `pages` CursorPages, nullable — Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.
    - `type` 'pages' — the type of object `pages`.
    - `page` integer — The current page
    - `next` StartingAfterPaging, nullable
      - `per_page` integer — The number of results to fetch per page.
      - `starting_after` string, nullable — The cursor to use in the next request to get the next page of results.
    - `per_page` integer — Number of results per page
    - `total_pages` integer — Total number of pages
  - `total_count` integer — The total number of companies.
  - `data` Company[] — An array containing Company Objects.
    - `type` 'company' — Value is `company`
    - `id` string — The Intercom defined id representing the company.
    - `name` string — The name of the company.
    - `app_id` string — The Intercom defined code of the workspace the company is associated to.
    - `plan` object
      - `type` string — Value is always "plan"
      - `id` string — The id of the plan
      - `name` string — The name of the plan
    - `company_id` string — The company id you have defined for the company.
    - `remote_created_at` integer — The time the company was created by you.
    - `created_at` integer — The time the company was added in Intercom.
    - `updated_at` integer — The last time the company was updated.
    - `last_request_at` integer — The time the company last recorded making a request.
    - `size` integer — The number of employees in the company.
    - `website` string — The URL for the company website.
    - `industry` string — The industry that the company operates in.
    - `monthly_spend` integer — How much revenue the company generates for your business.
    - `session_count` integer — How many sessions the company has recorded.
    - `user_count` integer — The number of users in the company.
    - `custom_attributes` object — The custom attributes you have set on the company.
    - `tags` object — The list of tags associated with the company
      - `type` 'tag.list' — The type of the object
      - `tags` TagBasic[]
        - `type` string — value is "tag"
        - `id` string — The id of the tag
        - `name` string — The name of the tag
    - `segments` object — The list of segments associated with the company
      - `type` 'segment.list' — The type of the object
      - `segments` Segment[]
        - `type` 'segment' — The type of object.
        - `id` string — The unique identifier representing the segment.
        - `name` string — The name of the segment.
        - `created_at` integer — The time the segment was created.
        - `updated_at` integer — The time the segment was updated.
        - `person_type` 'contact' | 'user' — Type of the contact: contact (lead) or user.
        - `count` integer, nullable — The number of items in the user segment. It's returned when `include_count=true` is included in the request.

## Other responses

- `401` — Unauthorized
- `404` — Company Not Found

---

[API](https://skmtc.net/intercom/apis/intercom-api.md) · [All operations](https://skmtc.net/intercom/apis/intercom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/intercom/intercom-api/revisions/9517e80f2642/schema)