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

# Retrieve Companies

`GET /v1/companies`

Retrieve the list of companies based on provided IDs.
Credit Note: Each company will contain it's full deep data and it will consumes 1 credit, unless the company was already accessed within the last 12 months.

:::info
Requires the `companies:read` OAuth2 scope.
:::

## Query parameters

- `ids` string, required
- `account_id` string, required
- `include` 'group_company' | 'tags' | 'lists' | 'web_visits' | 'icps' | 'crm_connections' | 'crm_connections.crm_record' | 'crm_connections.crm_record.crm_owner' | 'crm_suggestions' | 'crm_suggestions.crm_record' | 'crm_suggestions.crm_record.crm_owner' | 'crm_group_connections' | 'crm_group_connections.crm_connection' | 'crm_group_connections.crm_connection.crm_record' | 'crm_group_connections.crm_connection.crm_record.crm_owner'

## Response `200`

Success

- object
  - `data` CompanyV1[], required
    - `type` 'company', required — The type of the object
    - `id` string, required — The Leadfeeder company ID.
    - `attributes` object, required
      - `address` object, required
        - `street_address` string, nullable — The company's primary street address.
        - `street_name` string, nullable — The street name part of the company's primary address.
        - `street_number` string, nullable — The street number part of the company's primary address. This field does not necessarily contain a number, values like 1st, 23-35 or 13A are also common.
        - `postal_code` string, nullable — The postal code related to the company's physical location. The format varies by country.
        - `city` string, nullable — The city name.
        - `country` string, nullable — The country name.
        - `country_code` string, nullable — This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
        - `region` string, nullable — The name of the region in native language."
        - `region_code` string, nullable — The code for the region. For European companies the NUTS1-3 schema is used. For companies outside of Europe values that comply with ISO 3166-2 with underscores are returned.
        - `geo` object, nullable
          - `latitude` number, nullable — The latitude of the geographical point.
          - `longitude` number, nullable — The longitude of the geographical point.
      - `alternative_names` string[], required — An array of alternate / previous spellings of the company name.
      - `alternative_urls` string[], required — A set of alternative URLs related to the company.
      - `custom_fields` object, required — A dictionary of custom field values, indexed by their unique field IDs.
      - `description` string, nullable, required — A text containing information about the company (native language)
      - `earnings` object, nullable, required
        - `currency` string, nullable, required — Currency of the financial value.
        - `year` number, nullable, required — Year when the financial values was reported (or estimated).
        - `value` number, nullable, required — The amount of the financial value.
        - `estimated` boolean, required — Whether the financial value was actually reported or is just an estimation.
      - `emails` object[], required — Email address(es) for the company (eg. info@, service@ or support@).
        - `address` string, required — A standard e-mail address.
      - `employee_count` integer, nullable, required — The currently known headcount for this company.
      - `employee_range` '1-10' | '11-100' | '101-500' | '501-1.000' | '1.001-5.000' | '5.001-10.000' | '10.000+' | 'null', nullable, required — A range indicator of the approximate headcount for this company.
      - `founded_year` integer, nullable, required — A number representing the year when the company was founded.
      - `industries` object, required — A list of the company's industries.
        - `nace` object[], required — A list of the company's NACE industry classifications, each with a human-readable `name` and a NACE `code`.
          - `name` string, required — The name of the industry.
          - `code` string, required — The unique identifier for the industry.
        - `wz` object[], required — A list of the company's WZ industry classifications, each with a human-readable `name` and a WZ `code`.
          - `name` string, required — The name of the industry.
          - `code` string, required — The unique identifier for the industry.
        - `industry` object[], required — A list of the company's internal industry classifications, each with a human-readable `name` and an internal `code` identifier.
          - `name` string, required — The name of the industry.
          - `code` string, required — The unique identifier for the industry.
      - `keywords` string[], required — An array of keywords about the company and its products that have been extracted from the website. They will be returned in your user's language.
      - `legal_form` string, nullable, required — The company's legal form (i.e. GmbH, SARL or Limited).
      - `logo_url` string, uri, nullable, required — The URL of the company's logo.
      - `meta` object, required
        - `has_updated_id` boolean, required — This field will be true if the ID of that company has changed internally. This can happen for example if two companies are merged together. If you've stored a reference to the company ID in your system you should update it with the most current ID that's sent back in the `id` field.
        - `do_not_contact` boolean, required — This field is set to true when the company does not want to be contacted for advertisement.
        - `num_contacts` integer, nullable, required — The amount of contacts that we can provide for this company.
      - `name` string, required — The legal name of the company
      - `net_worth` object, nullable, required
        - `currency` string, nullable, required — Currency of the financial value.
        - `year` number, nullable, required — Year when the financial values was reported (or estimated).
        - `value` number, nullable, required — The amount of the financial value.
        - `estimated` boolean, required — Whether the financial value was actually reported or is just an estimation.
      - `orientation` string[], required — The target audience(s) of the company. The value 'B2B' indicates that the company is primarily focused on business customers, while 'B2C' indicates a focus on individual consumers. The value 'OTHER' means it’s a public (likely non-commercial) service or institution.
      - `phones` object[], required — The central phone number(s) of the company.
        - `number` string, required — E.164 representation of a phone number.
        - `type` 'landline' | 'mobile' | 'fax', required — The type of phone number.
        - `blacklisted` boolean, required — Whether the company is not allowed to be contacted because it's part of a register like https://www.tpsonline.org.uk/pages/what_is_tps in the UK.
      - `previous_ids` string[], required — A list of former ids that the company was known by in the past. The ID may have changed for example due to a merger with another company. The list is empty if there are no previous IDs.
      - `register` object, required
        - `id` string, nullable, required — The company's registration number from the commercial register.
        - `location` string, nullable, required — The company's register location.
        - `status` 'active' | 'in_liquidation' | 'out_of_business' | 'non_company' | 'legacy' | 'null', nullable, required — The company's status in the commercial register.
      - `revenue` object, nullable, required
        - `currency` string, nullable, required — Currency of the financial value.
        - `year` number, nullable, required — Year when the financial values was reported (or estimated).
        - `value` number, nullable, required — The amount of the financial value.
        - `value_eur` number, nullable, required — The amount of the financial value, converted to EUR.
        - `estimated` boolean, required — Whether the financial value was actually reported or is just an estimation.
      - `role` 'single_entity' | 'group' | 'group_member' | 'null', nullable, required — This field indicates the role of the company within its group structure.
      - `social_media_profiles` object, required — List of social media pages.
        - `linkedin` object[]
          - `url` string
        - `instagram` object[]
          - `url` string
        - `facebook` object[]
          - `url` string
        - `twitter` object[]
          - `url` string
        - `youtube` object[]
          - `url` string
        - `pinterest` object[]
          - `url` string
        - `xing` object[]
          - `url` string
      - `url` string, nullable, required — The URL of the company website.
      - `vat_id` string, nullable, required — The company's VAT ID (tax ID).
      - `web_engagement` object, required — Web engagement data for a company.
        - `last_visit_date` string, date-time, nullable, required — The datetime of the last visit to the company's website.
      - `intent` object, required
        - `score` number, nullable, required — A decimal score (0-10) representing the level of buying intent predicted for the company, based on tracked activity over the past 90 days.
        - `score_tier` string, nullable, required — A categorical representation of the intent score, grouped into predefined tiers (`high`, `medium`, `low`) based on internal scoring thresholds.
        - `last_updated_at` string, nullable, required — The timestamp indicating when the intent score was last calculated or updated.
    - `relationships` object, required
      - `group_company` union, required — The group company head. The field may be null if the company is a single entity. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=group_company` url parameter.
        - object — The group company head. The field may be null if the company is a single entity.
          - `id` string, required — The Leadfeeder company ID.
          - `type` 'company', required
        - CompanyV1 — recursive
      - `tags` TagV1[] — Tags assigned to the company. By default this field is not displayed, but you can load it by passing the `include=tags` url parameter.
        - `type` 'tag', required — The type of the object
        - `id` string, required — The unique identifier for the tag
        - `attributes` object, required
          - `name` string, required — The human-readable name of the tag
          - `color` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9, required — List of supported color codes
          - `created_at` string, date-time, required — Date and time when the tag was created
          - `updated_at` string, date-time, required — Date and time when the tag was updated
        - `relationships` object, required
          - `created_by` object, required
            - `id` string, required — The Leadfeeder user ID.
            - `type` string, required
      - `lists` ListV1[] — Lists that include this company. By default this field is not displayed, but you can load it by passing the `include=lists` url parameter.
        - `type` 'list', required — The type of the object
        - `id` string, required — The unique identifier for the list
        - `attributes` object, required
          - `name` string, required — The human-readable name of the List
          - `scope` 'company' | 'contact', required — The scope type of the list
          - `created_at` string, date-time, required — Date and time when the list was created
          - `updated_at` string, date-time — Date and time when the list was updated
        - `relationships` object, required
          - `created_by` object, required
            - `id` string, required — The Leadfeeder user ID.
            - `type` string, required
      - `web_visits` WebVisitV1[] — Web visits associated with the company. It returns first 20 visits from last 7 days. By default this field is not displayed, but you can load it by passing the `include=web_visits` url parameter.
        - `type` 'web_visit', required — The type of the object
        - `id` string, required — The unique identifier for the web visit.
        - `attributes` object, required
          - `started_at` string, date-time, required — Datetime when the visit happened, rounded to minutes.
          - `source` string, required — Referrer traffic source (e.g. facebook).
          - `medium` string, nullable, required — Referrer traffic medium (e.g. cpc).
          - `campaign` string, nullable, required — Value of the utm_campaign or name of AdWords campaign.
          - `referring_url` string, nullable, required — Referrer URL.
          - `keyword` string, nullable, required — Referrer keyword (search engine search phrase).
          - `landing_page_path` string, required — Path of the first page the visitor viewed.
          - `page_depth` integer, required — Number of page views the visit contains.
          - `visit_length` integer, required — Duration of the visit in seconds.
          - `device_type` string, nullable, required — Identified device type.
          - `identifiers` object, required
            - `lf_client_id` string, required — Visitor's ID as seen by Leadfeeder.
            - `ga_client_ids` string[], required — Visitor IDs as seen by Google Analytics.
            - `adobe_cookies` object[], required — Visitor's Adobe cookies (MCMID, MCAAMB, MCAAMLH).
              - …
          - `visitor` object, required
            - `email` string, nullable, required — Email address of the identified visitor.
            - `first_name` string, nullable, required — First name of the identified visitor.
            - `last_name` string, nullable, required — Last name of the identified visitor.
          - `engagements` union[], required — The list of engagement events recorded during the visit. Each item represents one of: page view, form submit, file download, or video view.
            - union
              - …
        - `relationships` object, required
          - `location` VisitLocationV1, required
            - `type` 'visit_location', required — The type of the object
            - `id` string, required — The unique identifier for the location.
            - `attributes` object, required
              - …
          - `company` union, required — The company the contact is associated with. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` url parameter.
            - object
              - …
            - CompanyV1 — recursive
      - `crm_connections` CRMConnectionV1[] — CRM connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_connections` url parameter.
        - `type` 'crm_connection', required — The type of the object
        - `id` string, required — The unique identifier for the crm connection
        - `attributes` object, required
          - `send_visits` boolean, required
          - `primary` boolean, required
        - `relationships` object, required
          - `crm_record` union, required
            - CRMOrganizationV1
              - …
            - CRMContactV1
              - …
            - CRMLeadV1
              - …
      - `crm_suggestions` CRMSuggestionV1[] — CRM suggestions associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_suggestions` url parameter.
        - `type` 'crm_suggestion', required — The type of the object
        - `id` string, required — The unique identifier for the crm suggestion
        - `attributes` object, required
          - `match_score` number
        - `relationships` object, required
          - `crm_record` union, required
            - CRMOrganizationV1
              - …
            - CRMContactV1
              - …
            - CRMLeadV1
              - …
      - `crm_group_connections` CRMGroupConnectionV1[] — CRM group connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_group_connections` url parameter.
        - `type` 'crm_group_connection', required — The type of the object
        - `id` string, required — The unique identifier for the crm connection
        - `attributes` object, required
        - `relationships` object, required
          - `crm_connection` union, required
            - object
              - …
            - CRMConnectionV1
              - …
          - `company` union, required
            - object
              - …
            - CompanyV1 — recursive
      - `icps` ICPV1[] — Ideal Customer Profiles (ICPs) defined in the account that this company matches. By default this field is not displayed, but you can load it by passing the `include=icps` url parameter.
        - `type` string, required — The type of the object
        - `id` string, required — The unique identifier for the ICP
        - `attributes` object, required
          - `name` string, required — The human-readable name of the ICP
          - `created_at` string, date-time, required — Date and time when the ICP was created
          - `filters` object, required — Filter criteria that define this ICP, grouped by filter category. Categories with no configured criteria are omitted. The object is empty when the ICP has no filters configured.
            - `employee_count` object[] — Employee count range filters.
              - …
            - `industries` object[] — Industry filters.
              - …
            - `location` object[] — Location filters.
              - …
  - `meta` object, required
    - `credits` object, required
      - `charged` number, required — How many credits were consumed for this request.
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Invalid mandatory fields
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

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