From d9e1c756c947ef357340ed1cf3a374ec929b0db9 Mon Sep 17 00:00:00 2001
From: Renzo Pecoraro <renzo.pecoraro@northdata.de>
Date: Thu, 5 Feb 2026 11:35:06 +0100
Subject: [PATCH 1/3] Add Ownership section

---
 doc/data-api-userguide/data-api-userguide.md | 27 ++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/data-api-userguide/data-api-userguide.md b/doc/data-api-userguide/data-api-userguide.md
index a883840..3ca1073 100644
--- a/doc/data-api-userguide/data-api-userguide.md
+++ b/doc/data-api-userguide/data-api-userguide.md
@@ -339,8 +339,11 @@ Parameter name | Type | Explanation
 `extras` | boolean | true to include detail company data provided by 3rd parties
 
 If `history` is set to true, the `name`, `address` and `register` history is added to the API response. 
+
 If `history` is set to true in combination with `financials`, then the known financial history is added to the response.
+
 If `history` is set to true in combination with any of `relations`, `owners`, `ownerships` or `representatives`, then also formerly related companies and persons are included.
+
 While `owners` includes all shareholders, `relations` only includes majority shareholders.
 
 **Note**: Your search might return a large result set. In that case, please DO NOT use `relations=true`, as this may quickly lead to loading of hundreds of thousands of companies.
@@ -362,6 +365,30 @@ The following table summarizes the meaning of all relevant `group` and `dir` com
 `Interest`|subject entity owns the related entity|related entity owns the subject entity
 `Personal`|subject entity holds the personal role for the related entity|related entity holds the personal role for the subject entity
 
+###Ownership
+
+Setting the `owners` or `ownerships` parameters to true will retrieve the owners or ownerships of the subject company as described above.
+
+In addition, if you set `financials=true`, you may retrieve the `sharesPercent` and/or `sharesNominal` of such owners/ownerships relations. These fields describe the shares associated with the role.
+
+The resulting response would look for example like this (excerpt):
+
+```
+"roles": [
+  {
+    "date": "2015-06-10",
+    "dir": "Source",
+    "group": "Interest",
+    "name": "Shareholder",
+    "sharesNominal": {
+      "unit": "EUR",
+      "value": 120001.0
+    },
+    "sharesPercent": 100.0,
+    "type": "Shareholder"
+  }
+]
+```
 
 ### Events
 

From 59293a2eab91f4f606c75a53125d76a3822e7cdf Mon Sep 17 00:00:00 2001
From: Renzo Pecoraro <renzo.pecoraro@northdata.de>
Date: Thu, 5 Feb 2026 11:39:30 +0100
Subject: [PATCH 2/3] Add to TOC

---
 doc/data-api-userguide/data-api-userguide.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/data-api-userguide/data-api-userguide.md b/doc/data-api-userguide/data-api-userguide.md
index 3ca1073..06e6c04 100644
--- a/doc/data-api-userguide/data-api-userguide.md
+++ b/doc/data-api-userguide/data-api-userguide.md
@@ -30,6 +30,7 @@ Please see also:
     - [Identifying a company by internal company ID](#identifying-a-company-by-internal-company-id)
   - [Accessing company detail information](#accessing-company-detail-information)
     - [Relations](#relations)
+    - [Ownership](#ownership)
     - [Events](#events)
     - [Segment codes](#segment-codes)
     - [Extras provided by third parties](#extras-provided-by-third-parties)

From e59b11ae632aaa7e1b247b80f38731e81e328d80 Mon Sep 17 00:00:00 2001
From: Renzo Pecoraro <renzo.pecoraro@northdata.de>
Date: Thu, 5 Feb 2026 11:40:57 +0100
Subject: [PATCH 3/3] Fix formatting

---
 doc/data-api-userguide/data-api-userguide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/data-api-userguide/data-api-userguide.md b/doc/data-api-userguide/data-api-userguide.md
index 06e6c04..d08083a 100644
--- a/doc/data-api-userguide/data-api-userguide.md
+++ b/doc/data-api-userguide/data-api-userguide.md
@@ -366,7 +366,7 @@ The following table summarizes the meaning of all relevant `group` and `dir` com
 `Interest`|subject entity owns the related entity|related entity owns the subject entity
 `Personal`|subject entity holds the personal role for the related entity|related entity holds the personal role for the subject entity
 
-###Ownership
+### Ownership
 
 Setting the `owners` or `ownerships` parameters to true will retrieve the owners or ownerships of the subject company as described above.