Get an entity by ID

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>",
  "nationality": {},
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

GET

entities

{id}

Get an entity by ID

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>",
  "nationality": {},
  "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 entity by ID, including its 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

string

required

The unique gu1 ID of the entity to retrieve

Response

Returns the complete entity object with the following fields:

string

gu1’s internal entity ID

externalId

string

Your external identifier for this entity

organizationId

string

Your organization ID

type

string

Entity type (person or company)

name

string

Entity display name

taxId

string

Tax identification number

countryCode

string

ISO 3166-1 alpha-2 country code

nationality

string | null

ISO 3166-1 alpha-2 nationality at root (denormalized; may be null for legacy rows). Complements entityData.person.nationality / entityData.company.nationality.

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

Entity 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

Type-specific entity 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 entity creation

updatedAt

string

ISO 8601 timestamp of last update

deletedAt

string

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

Examples

Get Person Entity

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

Response Example - Person Entity

{
  "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",
  "nationality": "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
}

Response Example - Company Entity

{
  "id": "660e9511-f39c-52e5-b827-557766551111",
  "externalId": "company_789",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "12.345.678/0001-90",
  "countryCode": "BR",
  "nationality": "BR",
  "riskScore": 35,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 20,
      "description": "Company incorporated less than 2 years ago"
    },
    {
      "factor": "high_growth_industry",
      "impact": 15,
      "description": "Operating in high-growth tech sector"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T15:00:00Z",
    "documentsVerified": ["articles_of_incorporation", "tax_registration", "beneficial_owners"],
    "overallStatus": "approved"
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Sociedade Anônima",
      "tradeName": "Tech Solutions",
      "incorporationDate": "2020-06-15",
      "industry": "Software Development",
      "employeeCount": 50,
      "revenue": 5000000
    }
  },
  "attributes": {
    "website": "https://techsolutions.com.br",
    "registeredAddress": "Av. Paulista, 1000, São Paulo",
    "partnershipTier": "gold",
    "monthlyVolume": 250000
  },
  "currentEvaluation": {
    "id": "eval_xyz789",
    "entityId": "660e9511-f39c-52e5-b827-557766551111",
    "evaluationType": "kyb_assessment",
    "result": {
      "overallRisk": "medium",
      "financialRisk": "low",
      "reputationalRisk": "low",
      "complianceScore": 88,
      "recommendation": "approve_with_monitoring"
    },
    "confidence": 0.87,
    "evaluatedAt": "2024-10-03T15:05:00Z"
  },
  "createdAt": "2024-10-03T15:00:00.000Z",
  "updatedAt": "2024-10-03T15:05:00.000Z",
  "deletedAt": null
}

Response Example - Transaction Entity

{
  "id": "770f0622-g40d-63f6-c938-668877662222",
  "externalId": "txn_98765",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "transaction",
  "name": "Wire Transfer - $50,000",
  "taxId": null,
  "countryCode": "US",
  "nationality": null,
  "riskScore": 45,
  "riskFactors": [
    {
      "factor": "high_value_transaction",
      "impact": 30,
      "description": "Transaction amount exceeds $10,000 threshold"
    },
    {
      "factor": "wire_transfer",
      "impact": 15,
      "description": "Wire transfers carry higher fraud risk"
    }
  ],
  "status": "under_review",
  "kycVerified": false,
  "kycProvider": null,
  "kycData": null,
  "entityData": {
    "transaction": {
      "transactionId": "txn_98765",
      "type": "wire_transfer",
      "status": "completed",
      "amount": 50000,
      "currency": "USD",
      "paymentMethod": "bank_transfer",
      "originEntityId": "customer_12345",
      "destinationEntityId": "merchant_456",
      "transactedAt": "2024-10-03T14:30:00Z",
      "riskScore": 45,
      "flagged": true,
      "category": "business_payment",
      "description": "Payment for professional services"
    }
  },
  "attributes": {
    "ipAddress": "192.168.1.100",
    "deviceId": "device_abc123",
    "userAgent": "Mozilla/5.0...",
    "referenceNumber": "REF-2024-10-03-001"
  },
  "currentEvaluation": {
    "id": "eval_def456",
    "entityId": "770f0622-g40d-63f6-c938-668877662222",
    "evaluationType": "fraud_detection",
    "result": {
      "overallRisk": "medium",
      "fraudProbability": 0.35,
      "amlFlags": ["high_value", "cross_border"],
      "recommendation": "manual_review"
    },
    "confidence": 0.78,
    "evaluatedAt": "2024-10-03T14:32:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:32: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 entity to check their KYC status before approving a transaction:

const entity = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.kycVerified && entity.status === 'active') {
  // Proceed with transaction
  console.log('Customer verified, risk score:', entity.riskScore);
} else {
  // Request additional verification
  console.log('KYC verification required');
}

Risk Score Monitoring

Check the current risk score and factors for ongoing monitoring:

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

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

Evaluation Results Analysis

Access the latest AI evaluation to understand assessment details:

const entity = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (entity.currentEvaluation) {
  console.log('Evaluation confidence:', entity.currentEvaluation.confidence);
  console.log('Recommendation:', entity.currentEvaluation.result.recommendation);
  console.log('Risk assessment:', entity.currentEvaluation.result.overallRisk);
}

Next Steps

Update Entity - Modify entity attributes
List Entities - Query multiple entities
Request AI Analysis - Get risk assessment
View Entity Timeline - See entity history

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Response

​Examples

​Get Person Entity

​Response Example - Person Entity

​Response Example - Company Entity

​Response Example - Transaction Entity

​Error Responses

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​KYC Verification Check

​Risk Score Monitoring

​Evaluation Results Analysis

​Next Steps

Overview

Endpoint

Authentication

Path Parameters

Response

Examples

Get Person Entity

Response Example - Person Entity

Response Example - Company Entity

Response Example - Transaction Entity

Error Responses

404 Not Found

401 Unauthorized

500 Internal Server Error

Use Cases

KYC Verification Check

Risk Score Monitoring

Evaluation Results Analysis

Next Steps