Companies endpoint

Overview

The Company Search endpoint allows you to search for companies across multiple countries using a flexible set of filters. You can retrieve detailed company information including registration data, financial statements, LinkedIn data, and metadata timestamps.

The endpoint supports two modes:

Full Search Mode

Returns the complete company profile including registration details, enriched data (employees, keywords, group structure), financial statements across multiple currencies and consolidation levels, LinkedIn profile data, and metadata with data freshness timestamps.

Minified Search Mode

Returns only the MinifiedInfo object per company — a compact summary designed for efficient synchronization and listing. Each MinifiedInfo contains:

• Identifiers: Valu8Id, OrgNo, CompanyName, CountryCode
• Status: OperationalStatus (e.g., Active = 10, Dissolved = 50)
• Fiscal data: LastFiscalYearEnd, LocalCurrencyCode
• Group structure: UltimateParentOrgNo
• Website: Url
• Data freshness timestamps — use these to detect what has changed since your last sync:
  • CompanyInfoUpdatedAt — company registration data changed
  • FinancialsUpdatedAt — financial statements updated
  • BeneficialOwnerUpdatedAt — UBO/beneficial owner data changed
  • KeyPeopleUpdatedAt — board members or CEO changed
  • OwnersUpdatedAt — ownership structure changed
  • ContentUpdatedAt — broad content update (includes relations)
  • RelationsUpdatedAt — corporate group relationships changed

Typical use case: Call with MinifiedSearch = true periodically to get a list of all companies with their update timestamps. Compare timestamps against your local cache to identify which companies need a full re-fetch.

Note: Minified search mode cannot be combined with cursor-based pagination.

Authentication

All requests require authentication. Include your credentials via the configured authentication mechanism (e.g., Bearer token in the Authorization header). If authentication fails, the endpoint returns HTTP 401 Unauthorized.

Request

Request Body

Send a JSON POST body with the following fields:

Search Parameters

The SearchParameters field is a dictionary where each key is a filter name and each value is an array of one or more filter values.

{"SearchParameters": { "CountryCode": ["SE", "NO"], "OperationalStatus": [10], "DynamicSearch": ["technology consulting"] }}

Key rules:

• At least one search parameter is required.
• Providing a single value, e.g., "NetSales": [1000000], implies a minimum threshold. However, providing two values, "NetSales": [1000000, 2000000], defines a range.
• CountryCode values must match your authorized countries.
• Parameter names are case-insensitive.
• Financial parameters support year suffixes: NetSales_Year_2023.
• See _v2_search-parameters.md for the full parameter reference, or call GET /v2/companies/search-parameters for the live list scoped to your subscription.

Pagination: Pages vs Cursor

The API offers two pagination strategies. Choose page-based for interactive UIs and smaller result sets (up to 5,000 companies). Choose cursor-based for large exports and synchronization (up to 100,000 companies per search).

Page-based pagination

Use PageNumber (1–10) and PageSize (1–500). Maximum reach: page 10 × 500 = 5,000 companies. Results can be sorted with SortByColumn and SortByDirection, and you may use MinifiedSearch for lightweight listings.

{
  "PageNumber": 1,
  "PageSize": 100,
  "SearchParameters": {
    "CountryCode": ["SE", "NO"],
    "OperationalStatus": [10],
    "DynamicSearch": ["technology consulting"]
  }
}

Use CurrentPage, HasNext, and HasPrevious from the X-Pagination header to drive UI paging. See Section 4.2.

Cursor-based pagination

Use cursor mode when you need to walk through more than 5,000 companies—for example, a country-wide export or syncing all companies that match your filters.

How cursor pagination works

Each page is a separate POST /v2/companies call. The API returns up to PageSize companies (max 500) and an opaque cursor token in the X-Pagination response header. That token encodes the position in the result set; pass it back on the next request to continue where the previous call left off.

Important: When using Cursor, you cannot use MinifiedSearch, SortByColumn, SortByDirection, or PageNumber (other than the default 1). Cursor mode always returns full company profiles, sorted by Valu8Id ascending.

First request example:

{
  "Cursor": "*",
  "PageSize": 500,
  "SearchParameters": {
    "CountryCode": ["SE"]
  }
}

Next request example — use the cursor from the previous response header:

{
  "Cursor": "eyJTdGFydERDSUQiOjEwMSwiSXRlbUNvdW50ZXIiOjUwMH0=",
  "PageSize": 500,
  "SearchParameters": {
    "CountryCode": ["SE"]
  }
}

Example X-Pagination header on an intermediate page:

{
  "Count": 500,
  "TotalCount": 125000,
  "PageSize": 500,
  "TotalPages": 250,
  "Cursor": "eyJTdGFydERDSUQiOjUwMSwiSXRlbUNvdW50ZXIiOjUwMH0="
}

On the last page with data, Count may be less than PageSize. When there are no more companies, you typically receive an empty Companies array and Cursor is null in the header.

Integration tips

• Do not invent or modify cursor tokens—they are opaque and validated server-side. A bad token returns Cursor has not a valid value. (HTTP 400).
• TotalCount in X-Pagination reflects how many companies match the search; you can use it for progress UI, but always use cursor + empty Companies to detect completion.
• Page-based vs cursor: Use pages when you need sorting, minified results, or fewer than 5,000 records. Use cursor for large full-profile exports.
• Small lookups may omit Cursor on the first call and use PageNumber instead; for explicit, full iteration over large sets, always start with "*" and loop until done.
• Rate limits apply per request; use PageSize: 500 and reasonable backoff if you receive HTTP 429.

Maximum iteration limit

Cursor pagination is capped at 100,000 companies per search (across all pages in one cursor run). If you keep requesting pages after that cumulative limit, the API returns HTTP 400:

You are not allowed to iterate more than 100000 via cursor.

The limit applies to the same SearchParameters and cursor chain—not per HTTP call. To continue beyond 100,000, start a new search with narrower filters (for example, split by ContentUpdatedAt or CompanyInfoUpdatedAt date ranges), or use batch files.

Need more than 100,000 companies? If your integration needs a larger dataset—a full-country company export, periodic full sync, or anything above the cursor cap—use the Batch Files API instead. Batch files are pre-generated bulk exports (JSON Lines, Brotli-compressed) scoped to your account, with no cursor iteration limit. List available files with GET /v2/batches/batch-files, then download via GET /v2/batches/batch-file/{batchFileId}. Contact Valu8 support for batch types and schemas that match your subscription.

Sorting

Set SortByColumn to any sortable field name and SortByDirection to "ASC" or "DESC". If SortByColumn is not specified, results are sorted by Valu8Id ascending.

Use the search-parameters endpoint to discover which fields are sortable.

Response

Success Response (HTTP 200)

Returns a GetCompaniesResponse JSON body and an X-Pagination header.

Pagination Header (X-Pagination)

Every successful response includes an X-Pagination HTTP response header with pagination metadata as JSON:

Example header (page mode):

{"Count": 100, "TotalCount": 3542, "PageSize": 100, "TotalPages": 36, "CurrentPage": 1, "HasPrevious": false, "HasNext": true}

Example header (cursor mode):

{"Count": 500, "TotalCount": 25000, "PageSize": 500, "TotalPages": 50, "Cursor": "eyJTdGFydERDSUQiOjUwMSwiSXRlbUNvdW50ZXIiOjUwMH0="}

Validation Error Response (HTTP 400)

Returned when request validation fails.

{"type": "https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request", "status": 400, "title": "One or more validation errors occurred.", "errors": { "parameters": [ "Searchparameters are missing.", "Currency is invalid." ] }}

Common validation errors:

Unauthorized Response (HTTP 401)

Returned with an empty body when authentication fails.

Response Body

The top-level JSON response body.

Note: ValidationResults is only included when there are validation errors (HTTP 400 path). On success it is omitted from the response.

Company Object

Each item in the Companies array. All sub-objects are conditionally included — they are omitted from the JSON when they have no data, keeping the response compact.

BasicDetails

Core identifying and registration information. Present in full search mode.

Addresses

Description

IndustryCode

Always present but lists may be empty.

IndustryItem

EnhancedDetails

Extended enriched company data. Present in full search mode.

MinifiedInfo

Lightweight summary returned when MinifiedSearch = true. Ideal for delta synchronization — compare the *UpdatedAt timestamp fields (e.g., CompanyInfoUpdatedAt, FinancialsUpdatedAt) against your local cache to detect changes since your last sync.

MetaData

Context for interpreting financial data and tracking data freshness.

LinkedIn

Company profile data from LinkedIn. All fields are conditionally included.

Financial Data Structures

Financial data uses a three-level nested dictionary structure (FinancialsCategories → FinancialsData → FinancialsTimeSeries) enabling flexible representation across years and statement categories. Figures are returned in the currency specified by your Currency request parameter. Consolidated vs unconsolidated blocks correspond to ConsolidationType.

Example shape:

"Financials": {
  "BalanceSheet": {
    "TotalAssets": { "2022": 1500000, "2023": 1750000 },
    "TotalEquity": { "2022": 800000, "2023": 900000 }
  },
  "ProfitAndLoss": {
    "NetSales": { "2022": 500000, "2023": 550000 },
    "EBITDA": { "2022": 75000, "2023": 82000 }
  }
}

FinancialsCategories

Structure: { "CategoryName": FinancialsData }

Each key is a financial statement category:

Line-item keys within each category are listed in Section 12.2. Not every company includes every category or line item — availability depends on country, reporting, and your subscription.

FinancialsData

Structure: { "LineItemKey": FinancialsTimeSeries }

Each key is a financial line item within its parent category. Keys use PascalCase and match the names in the tables below. The same key names are used as search/sort parameters (often with a _Year_{year} suffix when filtering by year).

BalanceSheet line items

ProfitAndLoss line items

CashFlow line items

KeyFinancialRatio line items

UltimateParent line items

OtherFinancialItems line items

FinancialsTimeSeries

Structure: { year: value }

Each key is a fiscal year (integer in JSON), each value is a numeric figure (double). A line item may be omitted entirely when no values exist for any year.

Enumeration Reference

Integer codes are returned as numbers in JSON. String codes are returned as text. Use GET /v2/companies/search-parameters for the full set of filterable values and code dictionaries available to your subscription (country codes, operational status, legal form, and more).

OperationalStatus

Used in BasicDetails.OperationalStatus and MinifiedInfo.OperationalStatus.

LegalForm

Used in BasicDetails.LegalForm

CompanyType (CompanyCategory)

Used in BasicDetails.CompanyType and GroupStructureCompany.CompanyType (group structure endpoint).

IndustryItemType

Used in IndustryCode.IndustryCodes[].Type and IndustryCode.WeightedGroupIndustryCodes[].Type.

ListingType

Used in BasicDetails.ListingType. Derived from whether the company is flagged as listed on a stock exchange.

FinancialFigureScale

Used in MetaData.FinancialFigureScale. Indicates the unit scale for numeric values in Financials and UnconsolidatedFinancials — apply the scale when interpreting amounts.

When FinancialFigureScale is not None, multiply displayed figures by the scale to obtain absolute currency amounts.

SearchableLegalForm

Subset of LegalForm values commonly exposed as the LegalForm search filter. Other legal form codes may still appear in responses.

ConsolidationType

Internal classification for financial statement consolidation. Helps interpret which response blocks apply:

JSON Serialization Behavior

To minimize response size, the following rules apply:

The absence of a field means "no data available" — not an error.

Companion Endpoint: Search Parameters

Endpoint: GET /v2/companies/search-parameters

Returns all available search parameter names, their data types, filtering controls, sortability, and value dictionaries (e.g., valid country codes, operational status codes). Use this endpoint to dynamically build search forms or validate parameters before calling the search endpoint.