Obtener una persona por ID

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

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

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

	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/{id}")

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

{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

GET

entities

{id}

Obtener una persona por ID

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

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

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

	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/{id}")

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

{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

Resumen

Recupera los detalles completos de una persona, incluyendo el estado de evaluación y la valoración de riesgo. Podés consultar una persona de tres formas:

Método	Endpoint	Cuándo usar
Por ID	`GET /entities/{id}`	Tenés el UUID interno de la entidad en gu1
Por external ID	`GET /entities/by-external-id/{externalId}`	Usás tu propio identificador (ej. `customer_12345`)
Por tax ID	`GET /entities/by-tax-id/{taxId}`	Tenés el documento fiscal (CUIT, CPF, etc.) y querés buscar la persona

Los tres devuelven el mismo objeto. El alcance de organización se aplica según tu API key.

Endpoints

Obtener por ID

GET http://api.gu1.ai/entities/{id}

string

required

ID único (UUID) de gu1 de la persona a recuperar

Obtener por external ID

GET http://api.gu1.ai/entities/by-external-id/{externalId}

string

required

Tu identificador externo de esta persona (el valor enviado al crear la entidad)

Obtener por tax ID

GET http://api.gu1.ai/entities/by-tax-id/{taxId}

string

required

Número de identificación fiscal (formato según país: CUIT Argentina, CPF Brasil, etc.). Debe coincidir con el tax ID almacenado de la entidad en tu organización.

Autenticación

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

Authorization: Bearer YOUR_API_KEY

Respuesta

Devuelve el objeto completo de la persona con los siguientes campos:

string

ID interno de entidad de gu1

string

Tu identificador externo para esta persona

string

Tu ID de organización

string

Siempre “person”

string

Nombre para mostrar de la persona

string

Número de identificación fiscal

string

Código de país ISO 3166-1 alpha-2

number

Puntuación de riesgo calculada de 0 (bajo riesgo) a 100 (alto riesgo)

array

Array de factores de riesgo identificados que contribuyen a la puntuación de riesgo

string

Estado de la persona: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Si la verificación KYC ha sido completada

string

Nombre del proveedor KYC utilizado (si aplica)

object

Datos de verificación KYC del proveedor

object

Estructura de datos específica de la persona

object

Atributos personalizados como pares clave-valor

object

Resultados de evaluación de IA más recientes (null si no existe evaluación)

id - ID de evaluación
entityId - ID de entidad
evaluationType - Tipo de evaluación realizada
result - Resultado de evaluación
confidence - Puntuación de confianza (0-1)
evaluatedAt - Marca de tiempo de evaluación

string

Marca de tiempo ISO 8601 de creación de la persona

string

Marca de tiempo ISO 8601 de última actualización

string

Marca de tiempo ISO 8601 de eliminación lógica (null si no está eliminada)

Ejemplos

Por ID (UUID)

curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const person = await response.json();

import requests
response = requests.get(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
person = response.json()
print(person)

Por external ID

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

const externalId = 'customer_12345';
const response = await fetch(
  `http://api.gu1.ai/entities/by-external-id/${encodeURIComponent(externalId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const person = await response.json();

import requests
response = requests.get(
    "http://api.gu1.ai/entities/by-external-id/customer_12345",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
person = response.json()

Por tax ID

curl -X GET "http://api.gu1.ai/entities/by-tax-id/20-12345678-9" \
  -H "Authorization: Bearer YOUR_API_KEY"

const taxId = '20-12345678-9';
const response = await fetch(
  `http://api.gu1.ai/entities/by-tax-id/${encodeURIComponent(taxId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const person = await response.json();

import requests
response = requests.get(
    "http://api.gu1.ai/entities/by-tax-id/20-12345678-9",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
person = response.json()

Ejemplo de Respuesta

{
  "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"
    },
    {
      "factor": "high_income_occupation",
      "impact": -10,
      "description": "Professional occupation with verified income"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T14:30:00Z",
    "documentsVerified": ["national_id", "proof_of_address"],
    "livenessCheck": "passed",
    "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",
    "customerSince": "2024-01-15",
    "accountTier": "premium"
  },
  "currentEvaluation": {
    "id": "eval_abc123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "evaluationType": "risk_assessment",
    "result": {
      "overallRisk": "low",
      "amlRisk": "low",
      "fraudRisk": "low",
      "complianceScore": 95,
      "recommendation": "approve"
    },
    "confidence": 0.92,
    "evaluatedAt": "2024-10-03T14:35:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:35:00.000Z",
  "deletedAt": null
}

Respuestas de Error

404 Not Found

{
  "error": "Entity not found"
}

401 Unauthorized

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

500 Internal Server Error

{
  "error": "Failed to fetch entity"
}

Casos de Uso

Verificación de KYC

Recuperar un cliente para verificar su estado KYC antes de aprobar una transacción:

const person = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (person.kycVerified && person.status === 'active') {
  // Proceder con la transacción
  console.log('Customer verified, risk score:', person.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('KYC verification required');
}

Monitoreo de Puntuación de Riesgo

Verificar la puntuación de riesgo actual y factores para monitoreo continuo:

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

if person['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"High risk person detected: {person['riskScore']}")
    print("Risk factors:", person['riskFactors'])
elif person['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Medium risk person: {person['riskScore']}")

Próximos Pasos

Actualizar Persona - Modificar atributos de persona
Listar Personas - Consultar múltiples personas
Crear Validación KYC - Iniciar verificación de identidad

​Resumen

​Endpoints

​Obtener por ID

​Obtener por external ID

​Obtener por tax ID

​Autenticación

​Respuesta

​Ejemplos

​Por ID (UUID)

​Por external ID

​Por tax ID

​Ejemplo de Respuesta

​Respuestas de Error

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Verificación de KYC

​Monitoreo de Puntuación de Riesgo

​Próximos Pasos

Resumen

Endpoints

Obtener por ID

Obtener por external ID

Obtener por tax ID

Autenticación

Respuesta

Ejemplos

Por ID (UUID)

Por external ID

Por tax ID

Ejemplo de Respuesta

Respuestas de Error

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de Uso

Verificación de KYC

Monitoreo de Puntuación de Riesgo

Próximos Pasos