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 company 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 company to retrieve

Response

Returns the complete company object with the following fields:
id
string
gu1’s internal entity ID
externalId
string
Your external identifier for this company
organizationId
string
Your organization ID
type
string
Always “company”
name
string
Company 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
Company status: active, inactive, under_review, approved, rejected, suspended
kycVerified
boolean
Whether KYB verification has been completed
kycProvider
string
Name of the KYB provider used (if applicable)
kycData
object
KYB verification data from the provider
entityData
object
Company-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 company creation
updatedAt
string
ISO 8601 timestamp of last update
deletedAt
string
ISO 8601 timestamp of soft deletion (null if not deleted)

Examples

Get Company

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": "business_12345",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskScore": 25,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 15,
      "description": "Business 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": {
    "company": {
      "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",
    "businessSince": "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

KYB Verification Check

Retrieve a business to check their KYB status before approving a transaction:
const company = await fetch(`http://api.gu1.ai/entities/${businessId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

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

Risk Score Monitoring

Check the current risk score and factors for ongoing monitoring:
company = requests.get(
    f'http://api.gu1.ai/entities/{company_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

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

Next Steps