Get a company 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 company, including current evaluation status and risk assessment. You can fetch a company 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. `business_456`)
By tax ID	`GET /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}

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:

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

Update Company - Modify company attributes
List Companies - Query multiple companies
Create KYB Validation - Start identity verification

Create a company automatically with enrichment List companies

⌘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

​KYB 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

KYB Verification Check

Risk Score Monitoring

Next Steps