List entities (persons and companies)

List

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', 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",
  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"

	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))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

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

{
  "entities": [
    {}
  ]
}

GET

entities

List

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', 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",
  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"

	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))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

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

{
  "entities": [
    {}
  ]
}

Overview

Retrieves a list of entities with optional filtering by type, country, tax ID, or external ID. Returns up to 100 entities per request.

Endpoint

GET http://api.gu1.ai/entities

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

string

Filter by entity type. Available values:

person
company

string

Filter by ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)

string

Filter by exact tax identification number

string

Filter by your external identifier

Response

array

Array of entity objects, each containing:

id - gu1’s internal ID
externalId - Your external ID
organizationId - Your organization ID
type - Entity type
name - Entity name
taxId - Tax ID
countryCode - Country code
nationality - Nationality (ISO 3166-1 alpha-2 at root, or null)
riskScore - Risk score (0-100)
riskFactors - Array of risk factors
status - Entity status
kycVerified - KYC verification status
kycProvider - KYC provider name
kycData - KYC verification data
entityData - Type-specific data
attributes - Custom attributes
createdAt - Creation timestamp
updatedAt - Last update timestamp
deletedAt - Deletion timestamp (null if active)

Examples

List All Entities

curl -X GET "http://api.gu1.ai/entities" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('http://api.gu1.ai/entities', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(`Found ${data.entities.length} entities`);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

data = response.json()
print(f"Found {len(data['entities'])} entities")

Filter by Entity Type

curl -X GET "http://api.gu1.ai/entities?type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?type=company',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
const companies = data.entities;
console.log(`Found ${companies.length} companies`);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'company'}
)

companies = response.json()['entities']
print(f"Found {len(companies)} companies")

Filter by Country

curl -X GET "http://api.gu1.ai/entities?country=BR&type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?country=BR&type=company',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.entities.length} Brazilian companies`);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'country': 'BR',
        'type': 'company'
    }
)

brazilian_companies = response.json()['entities']
print(f"Found {len(brazilian_companies)} Brazilian companies")

Find by External ID

curl -X GET "http://api.gu1.ai/entities?externalId=customer_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?externalId=customer_12345',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
const entity = data.entities[0]; // External IDs should be unique
console.log('Found entity:', entity.name);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'externalId': 'customer_12345'}
)

entities = response.json()['entities']
if entities:
    print(f"Found entity: {entities[0]['name']}")

Find by Tax ID

curl -X GET "http://api.gu1.ai/entities?taxId=20-12345678-9" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?taxId=20-12345678-9',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
if (data.entities.length > 0) {
  console.log('Entity found:', data.entities[0].name);
}

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'taxId': '20-12345678-9'}
)

entities = response.json()['entities']
if entities:
    print(f"Entity found: {entities[0]['name']}")

Response Example

{
  "entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "customer_12345",
      "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
      "type": "person",
      "name": "María González",
      "taxId": "20-12345678-9",
      "countryCode": "AR",
      "nationality": "AR",
      "riskScore": 25,
      "riskFactors": [
        {
          "factor": "new_customer",
          "impact": 15,
          "description": "Customer registered within last 30 days"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "overallStatus": "approved"
      },
      "entityData": {
        "person": {
          "firstName": "María",
          "lastName": "González",
          "dateOfBirth": "1985-03-15",
          "nationality": "AR",
          "occupation": "Software Engineer",
          "income": 85000
        }
      },
      "attributes": {
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678"
      },
      "createdAt": "2024-10-03T14:30:00.000Z",
      "updatedAt": "2024-10-03T14:35:00.000Z",
      "deletedAt": null
    },
    {
      "id": "660e9511-f39c-52e5-b827-557766551111",
      "externalId": "company_789",
      "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
      "type": "company",
      "name": "Tech Solutions S.A.",
      "taxId": "12.345.678/0001-90",
      "countryCode": "BR",
      "nationality": "BR",
      "riskScore": 35,
      "riskFactors": [
        {
          "factor": "new_business",
          "impact": 20,
          "description": "Company incorporated less than 2 years ago"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T15:00:00Z",
        "overallStatus": "approved"
      },
      "entityData": {
        "company": {
          "legalName": "Tech Solutions Sociedade Anônima",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-06-15",
          "industry": "Software Development",
          "employeeCount": 50,
          "revenue": 5000000
        }
      },
      "attributes": {
        "website": "https://techsolutions.com.br",
        "registeredAddress": "Av. Paulista, 1000, São Paulo"
      },
      "createdAt": "2024-10-03T15:00:00.000Z",
      "updatedAt": "2024-10-03T15:05:00.000Z",
      "deletedAt": null
    }
  ]
}

Use Cases

High Risk Entity Monitoring

Query all entities and filter by risk score in your application:

const response = await fetch('http://api.gu1.ai/entities', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const highRiskEntities = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskEntities.length} high-risk entities requiring review`);
highRiskEntities.forEach(entity => {
  console.log(`- ${entity.name} (Risk: ${entity.riskScore})`);
});

KYC Compliance Dashboard

Get all unverified entities for compliance dashboard:

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'person'}
)

entities = response.json()['entities']
unverified = [e for e in entities if not e['kycVerified']]

print(f"Unverified customers: {len(unverified)}")
for entity in unverified:
    print(f"- {entity['name']} ({entity['externalId']})")

Transaction Volume Analysis

List all transactions for a specific period (combine with date filtering in your app):

const response = await fetch(
  'http://api.gu1.ai/entities?type=transaction',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

const data = await response.json();
const transactions = data.entities;

const totalVolume = transactions.reduce((sum, txn) => {
  return sum + (txn.entityData?.transaction?.amount || 0);
}, 0);

console.log(`Total transaction volume: $${totalVolume.toLocaleString()}`);
console.log(`Transaction count: ${transactions.length}`);

Country-Specific Compliance

Get all entities from a specific country for regulatory reporting:

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'country': 'US'}
)

us_entities = response.json()['entities']

# Separate by type
companies = [e for e in us_entities if e['type'] == 'company']
persons = [e for e in us_entities if e['type'] == 'person']

print(f"US Companies: {len(companies)}")
print(f"US Persons: {len(persons)}")

Pagination

The API currently returns up to 100 entities per request. If you have more than 100 entities and need pagination:

Use specific filters to narrow down results (type, country, etc.)
Implement client-side pagination by storing the last createdAt timestamp
Contact support for enterprise pagination features

Example with timestamp-based pagination:

let allEntities = [];
let lastCreatedAt = null;

async function fetchAllEntities() {
  const response = await fetch('http://api.gu1.ai/entities?type=company', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });

  const data = await response.json();

  // Filter by last timestamp if this is not the first batch
  const newEntities = lastCreatedAt
    ? data.entities.filter(e => new Date(e.createdAt) > new Date(lastCreatedAt))
    : data.entities;

  allEntities = allEntities.concat(newEntities);

  if (newEntities.length > 0) {
    lastCreatedAt = newEntities[newEntities.length - 1].createdAt;
  }

  return allEntities;
}

Error Responses

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to search entities"
}

Limits

Maximum results per request: 100 entities
Query parameters: Can be combined for advanced filtering
Rate limits: Apply based on your plan tier

Next Steps

Get Entity Details - Retrieve complete information for a specific entity
Create Entity - Add new entities to your organization
Update Entity - Modify entity attributes
Batch Operations - Process multiple entities at once

​Overview

​Endpoint

​Authentication

​Query Parameters

​Response

​Examples

​List All Entities

​Filter by Entity Type

​Filter by Country

​Find by External ID

​Find by Tax ID

​Response Example

​Use Cases

​High Risk Entity Monitoring

​KYC Compliance Dashboard

​Transaction Volume Analysis

​Country-Specific Compliance

​Pagination

​Error Responses

​401 Unauthorized

​500 Internal Server Error

​Limits

​Next Steps

Overview

Endpoint

Authentication

Query Parameters

Response

Examples

List All Entities

Filter by Entity Type

Filter by Country

Find by External ID

Find by Tax ID

Response Example

Use Cases

High Risk Entity Monitoring

KYC Compliance Dashboard

Transaction Volume Analysis

Country-Specific Compliance

Pagination

Error Responses

401 Unauthorized

500 Internal Server Error

Limits

Next Steps