Skip to main content
GET
http://api.gu1.ai
/
entities
/
{id}
Get
curl --request GET \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>'
{
  "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 by ID, including current evaluation status and risk assessment.

​
Endpoint

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

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The unique gu1 ID of the person to retrieve

​
Response

Returns the complete person object with the following fields:
​
id
string
gu1’s internal entity ID
​
externalId
string
Your external identifier for this person
​
organizationId
string
Your organization ID
​
type
string
Always “person”
​
name
string
Person display name
​
taxId
string
Tax identification number
​
countryCode
string
ISO 3166-1 alpha-2 country code
​
riskScore
number
Calculated risk score from 0 (low risk) to 100 (high risk)
​
riskFactors
array
Array of identified risk factors contributing to the risk score
​
status
string
Person status: active, inactive, under_review, approved, rejected, suspended
​
kycVerified
boolean
Whether KYC verification has been completed
​
kycProvider
string
Name of the KYC provider used (if applicable)
​
kycData
object
KYC verification data from the provider
​
entityData
object
Person-specific data structure
​
attributes
object
Custom attributes as key-value pairs
​
currentEvaluation
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
​
createdAt
string
ISO 8601 timestamp of person creation
​
updatedAt
string
ISO 8601 timestamp of last update
​
deletedAt
string
ISO 8601 timestamp of soft deletion (null if not deleted)

​
Examples

​
Get Person

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

​
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