Skip to main content
GET
/
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, including current evaluation status and risk assessment. You can fetch a person in three ways:
MethodEndpointUse when
By IDGET /entities/{id}You have gu1’s internal entity UUID
By external IDGET /entities/by-external-id/{externalId}You use your own identifier (e.g. customer_12345)
By tax IDGET /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}
​
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}
​
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}
​
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:
​
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 by ID (UUID)

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

​
Get by external ID

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

​
Get by tax ID

curl -X GET "http://api.gu1.ai/entities/by-tax-id/20-12345678-9" \
  -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