List persons

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 persons with optional filtering by country, tax ID, or external ID. Returns up to 100 persons per request.

Endpoint

GET http://api.gu1.ai/entities?type=person

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

string

required

Must be set to person to retrieve only persons

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 person objects, each containing:

id - gu1’s internal ID
externalId - Your external ID
organizationId - Your organization ID
type - Always “person”
name - Person name
taxId - Tax ID
countryCode - Country code
riskScore - Risk score (0-100)
riskFactors - Array of risk factors
status - Person status
kycVerified - KYC verification status
kycProvider - KYC provider name
kycData - KYC verification data
entityData - Person-specific data
attributes - Custom attributes
createdAt - Creation timestamp
updatedAt - Last update timestamp
deletedAt - Deletion timestamp (null if active)

Examples

List All Persons

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

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

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

import requests

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

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

Filter by Country

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

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

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

import requests

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

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

Find by External ID

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

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

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

import requests

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

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

Find by Tax ID

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

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

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

import requests

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

entities = response.json()['entities']
if entities:
    print(f"Person 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",
      "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
    }
  ]
}

Use Cases

High Risk Customer Monitoring

Query all persons and filter by risk score:

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

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

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

KYC Compliance Dashboard

Get all unverified customers for compliance dashboard:

import requests

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

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

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

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 persons
Query parameters: Can be combined for advanced filtering
Rate limits: Apply based on your plan tier

Next Steps

Get Person Details - Retrieve complete information for a specific person
Create Person - Add new persons to your organization
Update Person - Modify person attributes

​Overview

​Endpoint

​Authentication

​Query Parameters

​Response

​Examples

​List All Persons

​Filter by Country

​Find by External ID

​Find by Tax ID

​Response Example

​Use Cases

​High Risk Customer Monitoring

​KYC Compliance Dashboard

​Error Responses

​401 Unauthorized

​500 Internal Server Error

​Limits

​Next Steps

Overview

Endpoint

Authentication

Query Parameters

Response

Examples

List All Persons

Filter by Country

Find by External ID

Find by Tax ID

Response Example

Use Cases

High Risk Customer Monitoring

KYC Compliance Dashboard

Error Responses

401 Unauthorized

500 Internal Server Error

Limits

Next Steps