> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a company by ID

> Retrieve detailed information about a company — for company entities in the gu1 risk and compliance platform, with examples for get use cases.

## 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}
```

<ParamField path="id" type="string" required>
  The unique gu1 ID (UUID) of the company to retrieve
</ParamField>

### Get by external ID

```
GET http://api.gu1.ai/entities/by-external-id/{externalId}
```

<ParamField path="externalId" type="string" required>
  Your external identifier for this company (e.g. the value you sent when creating the entity)
</ParamField>

### Get by tax ID

```
GET http://api.gu1.ai/entities/by-tax-id/{taxId}
```

<ParamField path="taxId" type="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.
</ParamField>

## Authentication

Requires a valid API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Response

Returns the complete company object with the following fields:

<ResponseField name="id" type="string">
  gu1's internal entity ID
</ResponseField>

<ResponseField name="externalId" type="string">
  Your external identifier for this company
</ResponseField>

<ResponseField name="organizationId" type="string">
  Your organization ID
</ResponseField>

<ResponseField name="type" type="string">
  Always "company"
</ResponseField>

<ResponseField name="name" type="string">
  Company display name
</ResponseField>

<ResponseField name="taxId" type="string">
  Tax identification number
</ResponseField>

<ResponseField name="countryCode" type="string">
  ISO 3166-1 alpha-2 country code
</ResponseField>

<ResponseField name="riskScore" type="number">
  Calculated risk score from 0 (low risk) to 100 (high risk)
</ResponseField>

<ResponseField name="riskFactors" type="array">
  Array of identified risk factors contributing to the risk score
</ResponseField>

<ResponseField name="status" type="string">
  Company status: `active`, `inactive`, `under_review`, `approved`, `rejected`, `suspended`
</ResponseField>

<ResponseField name="kycVerified" type="boolean">
  Whether KYB verification has been completed
</ResponseField>

<ResponseField name="kycProvider" type="string">
  Name of the KYB provider used (if applicable)
</ResponseField>

<ResponseField name="kycData" type="object">
  KYB verification data from the provider
</ResponseField>

<ResponseField name="entityData" type="object">
  Company-specific data structure
</ResponseField>

<ResponseField name="attributes" type="object">
  Custom attributes as key-value pairs
</ResponseField>

<ResponseField name="currentEvaluation" type="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
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of company creation
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

<ResponseField name="deletedAt" type="string">
  ISO 8601 timestamp of soft deletion (null if not deleted)
</ResponseField>

## Examples

### Get by ID (UUID)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const company = await response.json();
  console.log(company);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      }
  )

  company = response.json()
  print(company)
  ```
</CodeGroup>

### Get by external ID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities/by-external-id/business_456" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const externalId = 'business_456';
  const response = await fetch(
    `http://api.gu1.ai/entities/by-external-id/${encodeURIComponent(externalId)}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const company = await response.json();
  ```

  ```python Python theme={null}
  import requests
  external_id = "business_456"
  response = requests.get(
      f"http://api.gu1.ai/entities/by-external-id/{external_id}",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  company = response.json()
  ```
</CodeGroup>

### Get by tax ID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities/by-tax-id/30-71234567-8" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const taxId = '30-71234567-8'; // e.g. CUIT (AR) or CNPJ (BR)
  const response = await fetch(
    `http://api.gu1.ai/entities/by-tax-id/${encodeURIComponent(taxId)}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const company = await response.json();
  ```

  ```python Python theme={null}
  import requests
  tax_id = "30-71234567-8"  # e.g. CUIT (AR) or CNPJ (BR)
  response = requests.get(
      f"http://api.gu1.ai/entities/by-tax-id/{tax_id}",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  company = response.json()
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "Entity not found"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to fetch entity"
}
```

## Use Cases

### KYB Verification Check

Retrieve a business to check their KYB status before approving a transaction:

```javascript theme={null}
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:

```python theme={null}
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](/en/api-reference/company/update) - Modify company attributes
* [List Companies](/en/api-reference/company/list) - Query multiple companies
* [Create KYB Validation](/en/use-cases/kyc/create-validation) - Start identity verification