---
title: "Znajdź firmy podobne do Twoich leadów"
method: POST
path: "/companies/similar"
tags: ["Leady"]
---

# Znajdź firmy podobne do Twoich leadów

`POST /companies/similar`

## Request

- Base URL: `https://outreachpilot.pl/api/v1`
- URL: `https://outreachpilot.pl/api/v1/companies/similar`
- Auth: HTTP bearer

Buduje profil z 1-50 wzorców (leadów z Twojej bazy albo wygranych deali) i szuka firm podobnych w rejestrach publicznych na żywo: CEIDG i feed nowych spółek KRS. Profil obejmuje PKD 2007 i 2025, lokalizację, formę prawną, wiek firmy, stronę, oceny i sygnały Radaru. Każdy wynik ma ocenę 0-100 i dowody `why` („Dlaczego podobna”). Pomija firmy, które już masz (całe konto), i adresy z list wykluczeń. To PODGLĄD: niczego nie zapisuje, nie zużywa limitu leadów i nie zwraca e-maili ani telefonów. Zapytania do CEIDG idą wspólnym budżetem rejestru: gdy jest zajęty, odpowiedź jest częściowa (`sources.ceidg.status`, `notes`). `workspace_id` zawęża wzorce do klienta agencji. Wymaga zakresu `leads:scrape`.

**Wymagany zakres klucza:** `leads:scrape`.

## Request body

- object
  - `lead_ids` string[]: ID leadów z Twojej bazy, do których szukamy podobnych firm (wzorce, 1-50). Podaj to albo `won_deals`.
  - `won_deals` boolean: `true` = wzorcami są firmy na etapie „wygrany” w lejku (do 50, największe deale najpierw). Użyj zamiast `lead_ids`.
  - `without_dimensions` string[]: Wymiary profilu pominięte w szukaniu i rankingu, np. `["location"]` szuka w całej Polsce.
  - `limit` integer: Ile firm zwrócić (1-50), od najbardziej podobnych.
  - `workspace_id` string: Klient agencji (ID z `GET /workspaces`) albo `default` dla „Mojej firmy”: wzorce są brane tylko z tego klienta. Bez pola: całe konto.

## Response `200`

Sukces.

- object
  - `data` SimilarCompaniesResult, required
    - `seeds_used` integer, required: Ile wzorców weszło do profilu.
    - `profile` object[], required
      - `dimension` string, required
      - `label` string, required
      - `status` string, required: `active`, `disabled`, `low_coverage`, `no_data` albo `info_only`.
      - `chips` string[], required: Np. `PKD 43.22.Z · 8 z 10 wzorców`.
    - `candidates` object[], required: Firmy z rejestrów, od najbardziej podobnych. Bez e-maili, telefonów i stron: kontakt dociągamy przy zapisie.
      - `id` string, required: Id karty: `ceidg:<id>` albo `krs:<numer>`.
      - `source` 'ceidg' | 'krs', required
      - `ceidg_id` string, nullable, required: Id firmy w CEIDG (tylko firmy z CEIDG); do `import_ceidg_companies` w MCP albo zapisu w aplikacji.
      - `radar_key` string, nullable, required: Klucz karty Radaru `krs:<numer>` (tylko spółki z feedu KRS).
      - `name` string, required
      - `nip` string, nullable, required
      - `regon` string, nullable, required
      - `city` string, nullable, required
      - `voivodeship` string, nullable, required
      - `pkd` string[], required: Znane kody PKD (dla firm z CEIDG: kod, o który pytaliśmy rejestr).
      - `legal_form` 'jdg' | 'spolka', nullable, required
      - `registered_at` string, nullable, required: Data rejestracji firmy (YYYY-MM-DD).
      - `score` integer, required: Podobieństwo do profilu wzorców, 0-100.
      - `why` object[], required: Dowody „Dlaczego podobna”.
        - `dimension` string, required: Wymiar profilu (`pkd`, `location`, ...) albo `registry` (fakt z rejestru bez wagi).
        - `label` string, required: Np. `PKD 43.22.Z`.
        - `detail` string, nullable, required: Pokrycie we wzorcach, np. `8 z 10 wzorców`.
        - `strength` 'strong' | 'partial' | 'info', required
    - `sources` object, required
      - `ceidg` object, required
        - `status` 'ok' | 'empty' | 'partial' | 'busy' | 'unavailable' | 'skipped', required
        - `found` integer, required
        - `queries_run` integer, required
        - `retry_after_seconds` integer, nullable, required: Gdy budżet CEIDG był zajęty: za ile sekund warto ponowić.
      - `krs` object, required
        - `status` 'ok' | 'empty' | 'partial' | 'busy' | 'unavailable' | 'skipped', required
        - `found` integer, required
        - `queries_run` integer, required
    - `excluded` object, required
      - `already_in_database` integer, required: Firmy pominięte, bo masz je już w bazie (całe konto).
      - `on_exclusion_list` integer, required: Firmy pominięte przez listy wykluczeń.
    - `notes` string[], required: Uwagi po polsku, np. gdy rejestr CEIDG jest obciążony i wynik jest częściowy.

## Other responses

- `400`: Nieprawidłowe żądanie. Kody: `invalid_request`.
- `401`: Brak, zły, odwołany lub wygasły klucz (`missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `account_inactive`).
- `403`: Plan nie obejmuje API (`plan_upgrade_required`, odpowiedź zawiera informacje o planie; nie dotyczy tras wtyczki z kluczem `extension:*`) albo klucz nie ma wymaganego zakresu (`insufficient_scope`).
- `404`: Nie znaleziono. Kody: `not_found`.
- `422`: Błąd walidacji. Kody: `validation_error`.
- `429`: Błąd. Kody: `rate_limit_exceeded`.
- `503`: Usługa chwilowo niedostępna. Kody: `service_unavailable`.

---

[API](https://skmtc.dev/outreachpilot/apis/outreachpilot-api.md) · [All operations](https://skmtc.dev/outreachpilot/apis/outreachpilot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/outreachpilot/apis/outreachpilot-api/revisions/2262dabfb07c?raw)