Search and list companies
Uses the same search dataset as the public site. Filters combine with AND where applicable.
Response: data is one page of rows; pagination has limit, offset, total, hasMore, and optionally cursor when cursor-based paging is used.
For a single company’s full profile, use GET /companies/krs/{krs} (KRS court number).
Parameter details are documented on each query field below.
Pagination mode
offset and cursor are mutually exclusive in client usage. If both are sent, the server returns 400 CONFLICTING_PARAMETERS.
Use offset for shallow interactive browsing and cursor for deep paging/export flows.
Cursor pagination is ordered by entity_id ascending; cursor is the last entity_id from the prior page.
Because datasets can change between requests, deep paging may still observe occasional duplicates or skips.
With cursor mode, pagination.total may be unavailable and returned as -1; rely on hasMore.
Default ordering (offset mode)
- without q: has_email desc, then has_website desc, then revenue_total desc, then extracted_at desc, then entity_id asc.
- with q: same ordering as above (not TF-IDF/full-text relevance ranking).
- offset pagination is intended for interactive browsing; for deterministic deep traversal use cursor mode.
Financial filter semantics (for /companies and /companies/count)
- financial range filters are evaluated on the latest indexed financial snapshot per company (search index row).
- companies with null value for a filtered metric do not match that metric filter.
- when last_report_year_* is combined with financial metric filters, both are evaluated against the same indexed reporting snapshot.
Request
- Base URL: https://compabase.com/api/v1
- URL: https://compabase.com/api/v1/companies
- Auth: one of:
- API key in header X-API-Key
- HTTP bearer
Query parameters
Free-text search (company name and identifiers). Digits are treated as a possible KRS/NIP/REGON lookup. Whitespace is trimmed. Matching strategy: - identifier-like numeric input: identifier lookup path is used first. For 10-digit numeric values, exact match is attempted against KRS (registry_number) and NIP; an exact match is also attempted against REGON as stored in the index. For other numeric lengths, prefix matching is used for those identifier fields. - textual input: case-insensitive substring match on company name (ILIKE %q%). Numeric lookup has priority over text-name matching when q contains only digits. Example: q=0000028860 is treated as identifier lookup (not generic relevance search).
Keyword filter with OR semantics. Pass a comma-separated list, or repeat the parameter. Each keyword must be at least 2 characters after trimming. Empty tokens are ignored. Duplicate tokens may appear and are not guaranteed to be deduplicated server-side. Mixing repeated params and CSV is supported (e.g. keywords=a,b&keywords=c).
Page size. Default: 20. GET /companies caps at 100 per request. For bulk pulls use GET /companies/export (or limit > 100 on /companies via API key), capped at 500 per page. For deep traversal, page with cursor. Quota accounting: monthly quota counts each HTTP request. Row count in the page does not change the cost. Example: limit=500 still consumes 1 request from monthly quota.
Zero-based row offset for classic offset pagination. Client contract: use either offset or cursor (not both). If both are provided, the server returns 400 CONFLICTING_PARAMETERS.
Optional cursor for pagination: entity_id of the last row from the previous page. Cursor paging is ordered by entity_id ascending. Use it for deep paging/export-style traversal. Do not combine with offset; if both are sent, request fails with 400 CONFLICTING_PARAMETERS. When present, the server may return pagination.total: -1 and include pagination.cursor for the next page.
PKD code (Polish business activity classification). Case-insensitive; trimmed and uppercased server-side. By default only the primary PKD (primary_only=true) is matched; set primary_only=false to match any code in all_pkd_codes.
Boolean filter syntax is accepted (true/false). Semantics: true (default) means pkd matches primary_pkd only. false means pkd can match any entry in all_pkd_codes.
Display/filter currency context for financial threshold filters. Allowed values: PLN, USD, EUR (case-insensitive). Default is PLN. For revenue_min / revenue_max, the API applies thresholds against: - revenue_total when currency=PLN - revenue_total_usd when currency=USD - revenue_total_eur when currency=EUR
Voivodeship / region filter. Compared to company_search.region case-insensitively (lowercased on the server). Use the same spelling as stored in data (e.g. Polish voivodeship names such as mazowieckie, śląskie). Common values include: dolnośląskie, małopolskie, mazowieckie, pomorskie, śląskie, wielkopolskie.
Exact postal code match (trimmed). Format depends on source data (e.g. 00-001).
City substring filter (case-insensitive ILIKE %city%).
Minimum total revenue (revenue_total). Currency depends on currency query param (PLN/USD/EUR). If currency is omitted, PLN is used. Values are in full currency units (not thousands), e.g. 1000000 = one million PLN. Evaluated against the latest indexed financial snapshot per company. Companies with null in the selected revenue column do not match this filter.
Maximum total revenue threshold in full units. Currency depends on currency query param (PLN/USD/EUR). If currency is omitted, PLN is used. If revenue_min > revenue_max, the API returns 400 with code INVALID_RANGE. Evaluated against the latest indexed financial snapshot per company. Companies with null in the selected revenue column do not match this filter.
Minimum operating revenue (net sales / operating revenue field from financials).
Minimum share capital (capital_total).
Minimum estimated company value (estimated_value), when present in search index.
Earliest registration year (registration_date filter): companies registered on or after YYYY-01-01.
Latest registration year (registration_date on or before YYYY-12-31).
Earliest exact registration date (registration_date on or after this day, inclusive), format YYYY-MM-DD. Takes precedence over registration_year_min. For companies registered today, pass today's date as both registration_date_min and registration_date_max. Applies to KRS companies and to JDG (CEIDG) rows merged into browse results.
Latest exact registration date (registration_date on or before this day, inclusive), format YYYY-MM-DD. Takes precedence over registration_year_max.
Earliest financial report period (financial_period_to on or after YYYY-01-01). When combined with financial metric filters, both are evaluated against the same indexed reporting snapshot.
Latest financial report period (financial_period_to on or before YYYY-12-31). When combined with financial metric filters, both are evaluated against the same indexed reporting snapshot.
Boolean filter syntax is accepted (true/false). Semantics: true applies positive filter (only active companies). false is syntactically valid and treated as no filter.
Legal form substring filter (case-insensitive ILIKE %legal_form%). Common values/phrases: spółka z ograniczoną odpowiedzialnością, spółka akcyjna, prosta spółka akcyjna, spółka komandytowa, jednoosobowa działalność gospodarcza.
Boolean filter syntax is accepted (true/false). Semantics: true applies positive filter (only companies with email). false is syntactically valid and treated as no filter.
Boolean filter syntax is accepted (true/false). Semantics: true applies positive filter (only companies with website). false is syntactically valid and treated as no filter.
Sort the result set by one column (default: completeness / revenue ranking). Rows without a value in that column are excluded while sorting. Text columns (name, nip, regon, city, region, postal_code) sort alphabetically; registration_date with dir=desc lists the newest registrations first (future-dated register errors are skipped); revenue_growth with dir=desc lists the fastest-growing companies (y/y revenue growth in %, latest vs previous financial year from KRS statements; combine with revenue_min to skip small companies). Not applied to free-text (q) or keywords searches, which keep relevance order.
Sort direction for sort (asc or desc, default desc).
Response
Paginated search results: data is an array of companies (one object per row on this page). Fields per row depend on filters and internal path; optional keys may be omitted or null.
Changes
No recorded changes to this operation across all 1 revision of this API.