---
title: "Match Companies"
method: POST
path: "/v1/companies/match"
tags: ["Companies", "v1"]
---

# Match Companies

`POST /v1/companies/match`

Find matching companies based on the provided input parameters.
Returns matching company IDs and basic company information.
**Important:** Each company object must include at least one of these required fields: `company_name`, `url`, `vat_id`, or `register_id`. Additional fields like email, phone, and address can improve match accuracy but cannot be used alone.
Credit Note: Matches do not consume credits. Credits are only used if you subsequently retrieve deep data for a company you haven't accessed within the last 12 months.

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

## Query parameters

- `account_id` string, required
- `max_results_per_company` number

## Request body

- object
  - `companies` union[], required
    - union
      - object
        - `company_name` string, required — The legal name of the company
        - `url` string, nullable — The URL of the company website.
        - `email` string — A standard e-mail address.
        - `phone` string — E.164 representation of a phone number.
        - `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)).
        - `city` string, nullable — The city name.
        - `postal_code` string, nullable — The postal code related to the company's physical location. The format varies by country.
        - `street` string — The full street address line, including the street name and house number.
        - `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.
        - `register_id` string, nullable — The company's registration number from the commercial register.
        - `register_location` string, nullable — The company's register location.
        - `vat_id` string, nullable — The company's VAT ID (tax ID).
      - object
        - `company_name` string — The legal name of the company
        - `url` string, nullable, required — The URL of the company website.
        - `email` string — A standard e-mail address.
        - `phone` string — E.164 representation of a phone number.
        - `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)).
        - `city` string, nullable — The city name.
        - `postal_code` string, nullable — The postal code related to the company's physical location. The format varies by country.
        - `street` string — The full street address line, including the street name and house number.
        - `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.
        - `register_id` string, nullable — The company's registration number from the commercial register.
        - `register_location` string, nullable — The company's register location.
        - `vat_id` string, nullable — The company's VAT ID (tax ID).
      - object
        - `company_name` string — The legal name of the company
        - `url` string, nullable — The URL of the company website.
        - `email` string — A standard e-mail address.
        - `phone` string — E.164 representation of a phone number.
        - `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)).
        - `city` string, nullable — The city name.
        - `postal_code` string, nullable — The postal code related to the company's physical location. The format varies by country.
        - `street` string — The full street address line, including the street name and house number.
        - `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.
        - `register_id` string, nullable — The company's registration number from the commercial register.
        - `register_location` string, nullable — The company's register location.
        - `vat_id` string, nullable, required — The company's VAT ID (tax ID).
      - object
        - `company_name` string — The legal name of the company
        - `url` string, nullable — The URL of the company website.
        - `email` string — A standard e-mail address.
        - `phone` string — E.164 representation of a phone number.
        - `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)).
        - `city` string, nullable — The city name.
        - `postal_code` string, nullable — The postal code related to the company's physical location. The format varies by country.
        - `street` string — The full street address line, including the street name and house number.
        - `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.
        - `register_id` string, nullable, required — The company's registration number from the commercial register.
        - `register_location` string, nullable — The company's register location.
        - `vat_id` string, nullable — The company's VAT ID (tax ID).

## Response `200`

Success

- object
  - `data` array[], required — The results of the match request. This field contains a list of arrays, each containing a list of matching companies as summary objects, along with their match score. The order will be the same as the order of the input objects that were provided when the match request was created.
    - CompanyMatchV1[]
      - `type` 'company_match', required — The type of the object
      - `id` string, required
      - `attributes` object, required
        - `match_score` number, float, required — The probability that we have matched the correct company. The field is returned as a float value and ranges between 0 and 1, with 1 being the equivalent of a 100% match probability.
      - `relationships` object, required
        - `company_summary` CompanySummaryV1, required
          - `type` 'company_summary', required — The type of the object
          - `id` string, required — The Leadfeeder company ID.
          - `attributes` object, required
            - `name` string, required — The legal name of the company
            - `url` string, nullable, required — The URL of the company website.
            - `logo_url` string, uri, nullable, required — The URL of the company's logo.
            - `address` object, required — Where the company is located.
              - …
            - `industries` object, required — A list of the company's industries.
              - …
            - `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.
            - `revenue` object, nullable, required
              - …
            - `role` 'single_entity' | 'group' | 'group_member' | 'null', nullable, required — This field indicates the role of the company within its group structure.
            - `register` object, required
              - …
            - `meta` object, required
              - …
          - `relationships` object, required
            - `group_company` object, nullable, required — The group company head. The field may be null if the company is a single entity.
              - …
  - `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)