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 company, including current evaluation status and risk assessment. You can fetch a company 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. business_456)
By tax IDGET /entities/by-tax-id/{taxId}You have the company’s tax ID (e.g. CUIT, CNPJ) and want to look them up
All three return the same company 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 company to retrieve

​
Get by external ID

GET http://api.gu1.ai/entities/by-external-id/{externalId}
​
externalId
string
required
Your external identifier for this company (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 company’s tax identification number (format depends on country: CUIT for Argentina, CNPJ 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 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 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/business_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get by tax ID

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