Obter uma pessoa 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}

Obter uma pessoa 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>"
}

Visão Geral

Recupera os detalhes completos de uma pessoa, incluindo status de avaliação e avaliação de risco. É possível consultar uma pessoa de três formas:

Método	Endpoint	Quando usar
Por ID	`GET /entities/{id}`	Você tem o UUID interno da entidade no gu1
Por external ID	`GET /entities/by-external-id/{externalId}`	Você usa seu próprio identificador (ex.: `customer_12345`)
Por tax ID	`GET /entities/by-tax-id/{taxId}`	Você tem o documento fiscal (CPF, CUIT, etc.) e quer buscar a pessoa

Os três retornam o mesmo objeto. O escopo da organização é aplicado conforme sua API key.

Endpoints

Obter por ID

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

string

required

ID único (UUID) do gu1 da pessoa a recuperar

Obter por external ID

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

string

required

Seu identificador externo desta pessoa (o valor enviado ao criar a entidade)

Obter por tax ID

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

string

required

Número de identificação fiscal (formato conforme o país: CPF Brasil, CUIT Argentina, etc.). Deve coincidir com o tax ID armazenado da entidade na sua organização.

Autenticação

Requer uma chave de API válida no cabeçalho de autorização:

Authorization: Bearer YOUR_API_KEY

Resposta

Retorna o objeto pessoa completo com os seguintes campos:

string

ID de entidade interno do gu1

string

Seu identificador externo para esta pessoa

string

ID da sua organização

string

Sempre “person”

string

Nome de exibição da pessoa

string

Número de identificação fiscal

string

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

number

Pontuação de risco calculada de 0 (baixo risco) a 100 (alto risco)

array

Array de fatores de risco identificados que contribuem para a pontuação de risco

string

Status da pessoa: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Se a verificação KYC foi concluída

string

Nome do provedor KYC usado (se aplicável)

object

Dados de verificação KYC do provedor

object

Estrutura de dados específica da pessoa

object

Atributos personalizados como pares chave-valor

object

Resultados da avaliação AI mais recente (null se não existir avaliação)

id - ID da avaliação
entityId - ID da entidade
evaluationType - Tipo de avaliação realizada
result - Resultado da avaliação
confidence - Pontuação de confiança (0-1)
evaluatedAt - Timestamp da avaliação

string

Timestamp ISO 8601 da criação da pessoa

string

Timestamp ISO 8601 da última atualização

string

Timestamp ISO 8601 da exclusão suave (null se não excluído)

Exemplos

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

Exemplo de Resposta

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

Respostas de Erro

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

Verificação de KYC

Recuperar um cliente para verificar seu status KYC antes de aprovar uma transação:

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') {
  // Prosseguir com a transação
  console.log('Customer verified, risk score:', person.riskScore);
} else {
  // Solicitar verificação adicional
  console.log('KYC verification required');
}

Monitoramento de Pontuação de Risco

Verificar a pontuação de risco atual e fatores para monitoramento contínuo:

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

if person['riskScore'] > 70:
    # Alto risco - acionar diligência aprimorada
    print(f"High risk person detected: {person['riskScore']}")
    print("Risk factors:", person['riskFactors'])
elif person['riskScore'] > 40:
    # Risco médio - aplicar monitoramento adicional
    print(f"Medium risk person: {person['riskScore']}")

Próximos Passos

Atualizar Pessoa - Modificar atributos da pessoa
Listar Pessoas - Consultar múltiplas pessoas
Criar Validação KYC - Iniciar verificação de identidade

​Visão Geral

​Endpoints

​Obter por ID

​Obter por external ID

​Obter por tax ID

​Autenticação

​Resposta

​Exemplos

​Por ID (UUID)

​Por external ID

​Por tax ID

​Exemplo de Resposta

​Respostas de Erro

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Verificação de KYC

​Monitoramento de Pontuação de Risco

​Próximos Passos

Visão Geral

Endpoints

Obter por ID

Obter por external ID

Obter por tax ID

Autenticação

Resposta

Exemplos

Por ID (UUID)

Por external ID

Por tax ID

Exemplo de Resposta

Respostas de Erro

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de Uso

Verificação de KYC

Monitoramento de Pontuação de Risco

Próximos Passos