Listar personas

Listar

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

Listar

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": [
    {}
  ]
}

Resumen

Recupera una lista de personas con filtrado opcional por país, ID fiscal o ID externo. Devuelve hasta 100 personas por solicitud.

Endpoint

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

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Parámetros de Consulta

string

required

Debe establecerse en person para recuperar solo personas

string

Filtrar por código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)

string

Filtrar por número de identificación fiscal exacto

string

Filtrar por tu identificador externo

Respuesta

array

Array de objetos de persona, cada uno conteniendo:

id - ID interno de gu1
externalId - Tu ID externo
organizationId - Tu ID de organización
type - Siempre “person”
name - Nombre de la persona
taxId - ID fiscal
countryCode - Código de país
riskScore - Puntuación de riesgo (0-100)
riskFactors - Array de factores de riesgo
status - Estado de la persona
kycVerified - Estado de verificación KYC
kycProvider - Nombre del proveedor KYC
kycData - Datos de verificación KYC
entityData - Datos específicos de la persona
attributes - Atributos personalizados
createdAt - Marca de tiempo de creación
updatedAt - Marca de tiempo de última actualización
deletedAt - Marca de tiempo de eliminación (null si está activa)

Ejemplos

Listar Todas las Personas

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

Filtrar por País

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

Buscar por ID Externo

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']}")

Buscar por 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']}")

Ejemplo de Respuesta

{
  "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
    }
  ]
}

Casos de Uso

Monitoreo de Clientes de Alto Riesgo

Consultar todas las personas y filtrar por puntuación de riesgo:

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})`);
});

Panel de Cumplimiento KYC

Obtener todos los clientes no verificados para el panel de cumplimiento:

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']})")

Respuestas de Error

401 Unauthorized

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

500 Internal Server Error

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

Límites

Máximo de resultados por solicitud: 100 personas
Parámetros de consulta: Pueden combinarse para filtrado avanzado
Límites de tasa: Aplican según tu nivel de plan

Próximos Pasos

Obtener Detalles de Persona - Recuperar información completa de una persona específica
Crear Persona - Agregar nuevas personas a tu organización
Actualizar Persona - Modificar atributos de persona

​Resumen

​Endpoint

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplos

​Listar Todas las Personas

​Filtrar por País

​Buscar por ID Externo

​Buscar por Tax ID

​Ejemplo de Respuesta

​Casos de Uso

​Monitoreo de Clientes de Alto Riesgo

​Panel de Cumplimiento KYC

​Respuestas de Error

​401 Unauthorized

​500 Internal Server Error

​Límites

​Próximos Pasos

Resumen

Endpoint

Autenticación

Parámetros de Consulta

Respuesta

Ejemplos

Listar Todas las Personas

Filtrar por País

Buscar por ID Externo

Buscar por Tax ID

Ejemplo de Respuesta

Casos de Uso

Monitoreo de Clientes de Alto Riesgo

Panel de Cumplimiento KYC

Respuestas de Error

401 Unauthorized

500 Internal Server Error

Límites

Próximos Pasos