Get materialized shareholders
curl --request GET \
--url http://api.gu1.ai/entities/{id}/shareholders \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/shareholders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/shareholders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/{id}/shareholders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/shareholders"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/shareholders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/shareholders")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"entityId": "<string>",
"shareholders": [
{}
],
"totalShareholders": 123,
"relationships": [
{}
],
"totalRelationships": 123
}API Reference
Get materialized shareholders
Read shareholders and other relationships already materialized for an entity, without running enrichment again.
GET
/
entities
/
{id}
/
shareholders
Get materialized shareholders
curl --request GET \
--url http://api.gu1.ai/entities/{id}/shareholders \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/shareholders"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/shareholders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/{id}/shareholders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/shareholders"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/shareholders")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/shareholders")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"entityId": "<string>",
"shareholders": [
{}
],
"totalShareholders": 123,
"relationships": [
{}
],
"totalRelationships": 123
}Overview
Returns the shareholders and other relationships already stored for a person or company. This is a read ofentities and entity_relationships. It does not call integrations, does not materialize new rows, and does not spend enrichment credits.
Use it after automatic creation when you need the same partners later. data.shareholders on that POST is only the creation response (id, name, taxId, type of children materialized in that run). Percentage and roles live on the relationship and are returned here in shareholderInfo.
QSA rows that were never turned into entities (for example a masked tax id) are not included. Those remain on Get normalized enrichment.
Requires granular permission entities:read on the API key (legacy fallback entities:read).
Endpoints
Both return the same body. The organization is taken from the API key.GET https://api.gu1.ai/entities/{id}/shareholders
GET https://api.gu1.ai/entities/by-tax-id/{taxId}/shareholders
Authentication
Authorization: Bearer YOUR_API_KEY
Path parameters
Tax id stored on the entity (CNPJ, CUIT, and so on). Digits are compared the same way as get by tax id. Use this on
GET /entities/by-tax-id/{taxId}/shareholders. If several rows match, the most recently created one is used.Query parameters
How many ownership levels to walk for
shareholders. 1 is direct owners only. Maximum 5. The list is flat and de-duplicated by entity id. Nested companies are expanded only when depth is greater than 1. relationships stays one hop from the root entity.Keep shareholders whose entity type is
person or company. Other links in relationships are not filtered.Minimum
riskScore, inclusive. Shareholders with riskScore: null are excluded when this or maxRiskScore is set.Minimum ownership percentage, inclusive. Shareholders without a stored percentage are excluded when this or
maxOwnershipPercentage is set.shareholders only, after depth is walked and before limit / offset. A company that does not match is still walked when depth is greater than 1, so a matching owner underneath it can still be returned. minRiskScore cannot be greater than maxRiskScore, and the same rule applies to the ownership bounds (400).
Response
200 with { "success": true, "data": { ... } }.
Ownership links use direction shareholder = source, owned entity = target, and a type of shareholder, owns, or controls. Those go in shareholders. Every other non-deleted link where this entity is source or target goes in relationships.
Materialized owners.
id,name,taxId,type,riskScore— the related entity.riskScoreisnullwhen the shareholder has no score.taxIdisnullwhen the API key lacksentities:read_sensitive.shareholderInfo.percentage—metadata.shareholdingPercentage, ornullshareholderInfo.roles—metadata.roles(empty array when absent)shareholderInfo.isActive—metadata.isActive, ornull
Other materialized counterparties.
id,name,taxId,type— the related entity.taxIdisnullwhen the API key lacksentities:read_sensitive.relationshipType— link type (for examplerelated_to)
200 and both arrays empty.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_ENTITY_ID | id is not a UUID |
| 404 | NOT_FOUND | No live entity with that id or tax id in your organization |
Example
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/shareholders?depth=1" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"data": {
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"shareholders": [
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"name": "João Silva",
"taxId": "12345678900",
"type": "person",
"riskScore": 25,
"shareholderInfo": {
"percentage": 60,
"roles": ["Sócio Administrador"],
"isActive": true
}
}
],
"totalShareholders": 1,
"relationships": [
{
"id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
"name": "Carlos Lima",
"taxId": "55566677788",
"type": "person",
"relationshipType": "related_to"
}
],
"totalRelationships": 1
}
}
Was this page helpful?