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

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:

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}

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:

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

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

Create a person automatically with enrichment List persons

⌘I

​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