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
string
Entity UUID. Use this on
GET /entities/{id}/shareholders.string
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
integer
default:"1"
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.integer
default:"100"
Page size applied separately to
shareholders and to relationships. Maximum 500.integer
default:"0"
How many items to skip in each array. Applied after the shareholder filters.
string
Keep shareholders whose entity type is
person or company. Other links in relationships are not filtered.string
Exact tax id of a shareholder. Digits are compared, so
123.456.789-00 matches 12345678900.number
Minimum
riskScore, inclusive. Shareholders with riskScore: null are excluded when this or maxRiskScore is set.number
Maximum
riskScore, inclusive.number
Minimum ownership percentage, inclusive. Shareholders without a stored percentage are excluded when this or
maxOwnershipPercentage is set.number
Maximum ownership percentage, inclusive.
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.
string
UUID of the entity that was queried.
array
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
number
Shareholders matching the filters, before
limit / offset.array
Other materialized counterparties.
id,name,taxId,typeβ the related entity.taxIdisnullwhen the API key lacksentities:read_sensitive.relationshipTypeβ link type (for examplerelated_to)
number
Other links, before
limit / offset. Filters do not change this count.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?