Relations

Overview

The Relations endpoint retrieves ownership, beneficial ownership, key person roles, and corporate structure relationships for one or more companies. You can search by Valu8 ID, organisation number, national identification number, or country with update-date filters.

Each result is a RelationsCompany containing the company profile plus Parents and Children relationship trees.

Authentication

All requests require authentication. Include your access token in the Authorization header:

Authorization: Bearer <access-token>

If authentication fails, the endpoint returns HTTP 401 Unauthorized.

Request

Request Body

Example request — search by organisation number:

{
  "SearchParameters": {
    "OrgNo": ["556000-1234"]
  },
  "PageSize": 10
}

Example request — search by country with date filter:

{
  "SearchParameters": {
    "CountryCode": ["SE"],
    "RelationsUpdatedAt": ["2024-01-01", "2024-12-31"]
  },
  "PageSize": 100
}

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.

Key rules:

• At least one search parameter is required.
• Parameter names are case-insensitive.
• CountryCode values must match your authorized countries.
• NationalIdentificationNumber requires CountryCode to also be specified.
• Organisation numbers and national IDs are normalized (whitespace and hyphens removed).
• Date parameters use format yyyy-MM-dd and accept one value (from date) or two values (from and to date).

Tip: Call GET /v2/relations/search-parameters to get the up-to-date list of available parameters.

Pagination: Cursor

Relations uses cursor-based pagination only (there is no PageNumber). Use cursor mode when you need to walk through more than a single page of results—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/relations 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.

First request example:

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

Next request example — use the cursor from the previous response header (value truncated for readability):

{
  "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 Relations 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 Relations to detect completion.
• Small lookups (a few OrgNo or Valu8Id values) may omit Cursor on the first call and still receive a Cursor in X-Pagination if more matches exist. 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 RelationsUpdatedAt date ranges or by region if your use case allows), or use batch files.

Need more than 100,000 companies? If your integration needs a larger dataset—a full-country relations 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 include relations data.

Response

Success Response (HTTP 200)

Returns a GetCompaniesRelationsByCountryCodeOrDcidsResponse JSON body and an X-Pagination header. An empty Relations array is a valid success response when no companies match.

Pagination Header (X-Pagination)

Every successful response includes an X-Pagination HTTP response header:

Example header:

{
  "Count": 100,
  "TotalCount": 3542,
  "PageSize": 100,
  "TotalPages": 36,
  "Cursor": "eyJTdGFydERDSUQiOjEwMSwiSXRlbUNvdW50ZXIiOjEwMH0="
}

Validation Error Response (HTTP 400)

{
  "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."
    ]
  }
}

Common validation errors:

Unauthorized Response (HTTP 401)

Returned with an empty body when authentication fails.

Response Body: GetCompaniesRelationsByCountryCodeOrDcidsResponse

Note: ValidationResults is only included on the HTTP 400 path. On success it is omitted.

RelationsCompany Object

Each item in the Relations array represents a company and its relationship graph.

Relation Object

Represents a related entity (company or person) in the ownership or control graph. Relations appear in both Parents and Children arrays.

Ownership

BeneficialOwnership

Extends Ownership with UBO-specific registration fields.

Role (Key Person)

Address

UBODetails

Company-level UBO registration summary on RelationsCompany.

Authorization and Data Filtering

The fields returned for each relation depend on your subscription's authorized areas per country. Fields you are not authorized to access are omitted from the response (not returned as null).

Protected identity handling: When IsProtected is true, personal fields (BirthDate, CountryCode, Addresses, Citizenships, CountryOfResidences) are masked as "Protected Identity". Name and national ID are also masked unless you have Hidden Person Access authorization.

JSON Serialization Behavior

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

Companion Endpoint: Search Parameters

Endpoint: GET /v2/relations/search-parameters

Returns all available search parameter names and their data types. Use this endpoint to discover valid filter names before calling the relations search endpoint.

Example response:

{
  "SearchParameters": [
    { "ParameterName": "Valu8Id", "Datatype": "number" },
    { "ParameterName": "NationalIdentificationNumber", "Datatype": "string" },
    { "ParameterName": "OrgNo", "Datatype": "string" },
    { "ParameterName": "ContentUpdatedAt", "Datatype": "date", "Description": "..." },
    { "ParameterName": "RelationsUpdatedAt", "Datatype": "date", "Description": "..." },
    { "ParameterName": "CountryCode", "Datatype": "string" }
  ]
}