Get a person by 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}

Get a person by 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>"
}

Overview

Retrieves complete details for a specific person, including current evaluation status and risk assessment. You can fetch a person in three ways:

Method	Endpoint	Use when
By ID	`GET /entities/{id}`	You have gu1’s internal entity UUID
By external ID	`GET /entities/by-external-id/{externalId}`	You use your own identifier (e.g. `customer_12345`)
By tax ID	`GET /entities/by-tax-id/{taxId}`	You have the person’s tax ID (e.g. CUIT, CPF) and want to look them up

All three return the same person object. The organization scope is enforced by your API key.

Endpoints

Get by ID

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

string

required

The unique gu1 ID (UUID) of the person to retrieve

Get by external ID

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

string

required

Your external identifier for this person (e.g. the value you sent when creating the entity)

Get by tax ID

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

string

required

The person’s tax identification number (format depends on country: CUIT for Argentina, CPF for Brazil, etc.). Must match the entity’s stored tax ID within your organization.

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Response

Returns the complete person object with the following fields:

string

gu1’s internal entity ID

string

Your external identifier for this person

string

Your organization ID

string

Always “person”

string

Person display name

string

Tax identification number

string

ISO 3166-1 alpha-2 country code

number

Calculated risk score from 0 (low risk) to 100 (high risk)

array

Array of identified risk factors contributing to the risk score

string

Person status: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Whether KYC verification has been completed

string

Name of the KYC provider used (if applicable)

object

KYC verification data from the provider

object

Person-specific data structure

object

Custom attributes as key-value pairs

object

Latest AI evaluation results (null if no evaluation exists)

id - Evaluation ID
entityId - Entity ID
evaluationType - Type of evaluation performed
result - Evaluation result
confidence - Confidence score (0-1)
evaluatedAt - Timestamp of evaluation

string

ISO 8601 timestamp of person creation

string

ISO 8601 timestamp of last update

string

ISO 8601 timestamp of soft deletion (null if not deleted)

Examples

Get by 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();
console.log(person);

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)

Get by 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
external_id = "customer_12345"
response = requests.get(
    f"http://api.gu1.ai/entities/by-external-id/{external_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
person = response.json()

Get by 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'; // e.g. CUIT (AR)
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
tax_id = "20-12345678-9"  # e.g. CUIT (AR)
response = requests.get(
    f"http://api.gu1.ai/entities/by-tax-id/{tax_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
person = response.json()

Response Example

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

Error Responses

404 Not Found

{
  "error": "Entity not found"
}

401 Unauthorized

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

500 Internal Server Error

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

Use Cases

KYC Verification Check

Retrieve a customer to check their KYC status before approving a transaction:

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') {
  // Proceed with transaction
  console.log('Customer verified, risk score:', person.riskScore);
} else {
  // Request additional verification
  console.log('KYC verification required');
}

Risk Score Monitoring

Check the current risk score and factors for ongoing monitoring:

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

if person['riskScore'] > 70:
    # High risk - trigger enhanced due diligence
    print(f"High risk person detected: {person['riskScore']}")
    print("Risk factors:", person['riskFactors'])
elif person['riskScore'] > 40:
    # Medium risk - apply additional monitoring
    print(f"Medium risk person: {person['riskScore']}")

Next Steps

Update Person - Modify person attributes
List Persons - Query multiple persons
Create KYC Validation - Start identity verification

​Overview

​Endpoints

​Get by ID

​Get by external ID

​Get by tax ID

​Authentication

​Response

​Examples

​Get by ID (UUID)

​Get by external ID

​Get by tax ID

​Response Example

​Error Responses

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​KYC Verification Check

​Risk Score Monitoring

​Next Steps

Overview

Endpoints

Get by ID

Get by external ID

Get by tax ID

Authentication

Response

Examples

Get by ID (UUID)

Get by external ID

Get by tax ID

Response Example

Error Responses

404 Not Found

401 Unauthorized

500 Internal Server Error

Use Cases

KYC Verification Check

Risk Score Monitoring

Next Steps