> ## 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.

# Create a company entity

> Create a new company with custom data — for company entities in the gu1 risk and compliance platform, with examples for create use cases.

## Overview

Creates a new company entity with the specified attributes. Company entities represent business organizations that you want to analyze for risk and compliance (KYB).

## Endpoint

```
POST http://api.gu1.ai/entities
```

## Authentication

Requires a valid API key in the Authorization header:

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

## Request Body

<ParamField body="type" type="string" required>
  Must be `company` for creating a company entity
</ParamField>

<ParamField body="externalId" type="string">
  Your unique identifier for this company in your system (optional but recommended)
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the company
</ParamField>

<ParamField body="countryCode" type="string" required>
  ISO 3166-1 alpha-2 country code (e.g., "US", "BR", "AR")
</ParamField>

<ParamField body="taxId" type="string">
  Tax identification number (validated based on country)

  <Tip>
    📋 See [Tax ID Formats by Country](/en/api-reference/entities/tax-id-formats) for accepted formats and validation rules for each country.
  </Tip>
</ParamField>

<ParamField body="operationalHours" type="object | null">
  Optional root operational hours for KYT rules. Same shape as [Create entity](/en/api-reference/entities/create).
</ParamField>

<ParamField body="attributes" type="object">
  Custom attributes as key-value pairs
</ParamField>

<ParamField body="entityData" type="object" required>
  Company-specific data structure (see below)
</ParamField>

<ParamField body="registrationDate" type="string">
  Company registration date in ISO 8601 datetime format (e.g., "2024-01-15T10:30:00Z")
</ParamField>

<ParamField body="isClient" type="boolean" default="false">
  Mark this company as a client/customer for tracking purposes
</ParamField>

<ParamField body="riskMatrixId" type="string | string[]">
  One or more risk matrix UUIDs (legacy: a single UUID string). If provided, after creation the system evaluates this company **only** against active rules tied to those matrices (unless `skipRulesExecution` is true). Same semantics as `riskMatrixIds` when you send a single id as a string. See [Risk Matrix Execution](#risk-matrix-execution) below.
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Preferred way to pass **multiple** matrices: ordered list of UUIDs belonging to your organization. When present and non-empty, it takes precedence over `riskMatrixId`.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean" default="false">
  Skip automatic rules execution after company creation. Use this to create the entity first and manually trigger rules later.
</ParamField>

<ParamField body="status" type="string" default="under_review">
  Initial status for the company. Options:

  * `active` - Company is active
  * `inactive` - Company is inactive
  * `blocked` - Company is blocked
  * `under_review` - Company is under review (default)
  * `suspended` - Company is suspended
  * `expired` - Company record has expired
  * `deleted` - Soft deleted
  * `rejected` - Company was rejected
</ParamField>

<ParamField body="autoExecuteIntegrations" type="object">
  Configure automatic execution of enrichments when creating the company.

  **Structure:**

  ```json theme={null}
  {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_nosis_extended_verification_enrichment",
      "ar_bcra_deudas_enrichment",
      "global_gueno_sanctions_enrichment"
    ],
    "excludeEnrichments": []
  }
  ```

  **Properties:**

  * `executeAllActiveEnrichments` (boolean) - Execute all active enrichment integrations configured in your organization
  * `enrichments` (string\[]) - Array of specific enrichment provider codes to execute

  **Example provider codes (Argentina company — must match `ValidProviderCodesEnum` strings):**

  * `ar_nosis_extended_verification_enrichment` — NOSIS extended company enrichment
  * `ar_bcra_deudas_enrichment` — BCRA debts enrichment
  * `ar_repet_entity_enrichment` — REPET entity / watchlist enrichment
  * `global_complyadvantage_sanctions_enrichment` — ComplyAdvantage sanctions enrichment
  * `global_gueno_sanctions_enrichment` — Gu1 sanctions enrichment (when configured)

  See [Provider codes](/en/api-reference/integrations/company-provider-codes) and the full [provider-codes](/en/api-reference/integrations/provider-codes) reference.
</ParamField>

<ParamField body="monitoring" type="object">
  Optional. Same as [Create entity](/en/api-reference/entities/create): use `monitoring.main` with `global_gueno_sanctions_enrichment: true` for **watchlist** mode when that enrichment runs from `autoExecuteIntegrations`. **Only this integration code is supported today.** Requires Marketplace monitoring enabled. Full examples: [Create entity — Gu1 example](/en/api-reference/entities/create#example-gu1-sanctions-monitoring-on-create).
</ParamField>

## Gu1 sanctions monitoring (company)

```json theme={null}
{
  "type": "company",
  "externalId": "co_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions",
      "industry": "Software"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
  }
}
```

## Company Entity Data Structure

The `entityData.company` object should contain:

```json theme={null}
{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other",
    "industry": "string",
    "websiteUrl": "string",
    "employeeCount": number,
    "revenue": number,
    "revenueCurrency": "string",
    "contactInfo": {
      "email": "string",
      "phone": "string",
      "alternativePhone": "string"
    },
    "address": "string | object (see Address Format note)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string"
  }
}
```

<Note>
  **Address Format**: The `address` field supports both formats:

  * **String format** (simple): `"Av. Paulista, 1000, São Paulo, SP, Brazil"`
  * **Object format** (structured):
    ```json theme={null}
    {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Suite 200",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "Brazil",
      "postalCode": "01310-100"
    }
    ```
</Note>

***

## Risk Matrix Execution

You can automatically execute one or more risk matrices (KYB compliance rules) when creating a company by providing `riskMatrixId` or `riskMatrixIds`.

### How It Works

1. **Get your Risk Matrix ID(s)** from the gu1 dashboard (format: UUID)
2. **Include `riskMatrixId` or `riskMatrixIds` in your creation request**
3. The system will:
   * Create the company entity
   * Execute all KYB rules in the matrix
   * Calculate risk score
   * Generate compliance alerts if needed
   * Update company status based on results

### Example with Risk Matrix

```json theme={null}
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech",
      "revenue": 5000000
    }
  }
}
```

### Example with multiple risk matrices

```json theme={null}
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}
```

### Combined with enrichments and Gu1 monitoring

```json theme={null}
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_nosis_extended_verification_enrichment",
      "ar_bcra_deudas_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}
```

See [Create entity — monitoring](/en/api-reference/entities/create#example-gu1-sanctions-monitoring-on-create).

***

## Response

<ResponseField name="success" type="boolean">
  Indicates if the company was created successfully
</ResponseField>

<ResponseField name="entity" type="object">
  The created company object including:

  * `id` - gu1's internal ID
  * `externalId` - Your external ID
  * `organizationId` - Your organization ID
  * `type` - Always "company"
  * `name` - Company name
  * `riskScore` - Initial risk score (0-100)
  * `status` - Company status
  * `entityData` - Company-specific data
  * `attributes` - Custom attributes
  * `createdAt` - Creation timestamp
  * `updatedAt` - Last update timestamp
</ResponseField>

<ResponseField name="rulesResult" type="object">
  Result of rules execution (only present when rules ran, e.g. when **skipRulesExecution** is `false` and a risk matrix is configured), including:

  * **success** (boolean) - Whether rules executed successfully
  * **rulesTriggered** (number) - Number of rules that were triggered
  * **alerts** (array) - Alerts generated by rules
  * **riskScore** (number) - Final calculated risk score
  * **decision** (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW\_REQUIRED)
  * **rulesExecutionSummary** (object) - Present when rules ran. See below for structure.
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  **At the root of the response** (same as transactions API). Same value as `rulesResult.rulesExecutionSummary`. **Only present when rules ran (e.g. skipRulesExecution is false).** Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. Omitted when rules did not run.

  * **rulesHit** (array) - Rules whose conditions were met. Each item: **name**, **description**, **score**, **priority**, **category**, **status** (e.g. `active`, `shadow`), **conditions** (array of `{ field, value, operator? }`), **actions** (alerts, suggestion, status, assignedUser).
  * **rulesNoHit** (array) - Rules that were evaluated but conditions were not met. Same structure as rulesHit (includes configured actions, not executed).
  * **actionsExecuted** (object) - Aggregated executed actions across all rules that hit: **alerts**, **suggestion** (`BLOCK` | `SUSPEND` | `FLAG`, highest weight), **status** (entity status applied, if any), **assignedUser** (`{ userId }`, if any), **customKeys** (array of strings, optional) — custom action keys from matched rules; for integrations/workflows.
  * **totalScore** (number) - Sum of **score** of all rules that hit and are **not** in `shadow` status.
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "company",
      "externalId": "company_789",
      "name": "Tech Solutions S.A.",
      "countryCode": "BR",
      "taxId": "12.345.678/0001-90",
      "entityData": {
        "company": {
          "legalName": "Tech Solutions Sociedade Anônima",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-06-15",
          "industry": "Software Development",
          "employeeCount": 50,
          "revenue": 5000000,
          "revenueCurrency": "BRL",
          "contactInfo": {
            "email": "contact@techsolutions.com.br",
            "phone": "+55 11 3456-7890"
          },
          "address": "Av. Paulista, 1000",
          "city": "São Paulo",
          "state": "SP",
          "country": "Brazil",
          "postalCode": "01310-100"
        }
      },
      "attributes": {
        "website": "https://techsolutions.com.br",
        "partnershipTier": "gold"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'company',
      externalId: 'company_789',
      name: 'Tech Solutions S.A.',
      countryCode: 'BR',
      taxId: '12.345.678/0001-90',
      entityData: {
        company: {
          legalName: 'Tech Solutions Sociedade Anônima',
          tradeName: 'Tech Solutions',
          incorporationDate: '2020-06-15',
          industry: 'Software Development',
          employeeCount: 50,
          revenue: 5000000,
          revenueCurrency: 'BRL',
          contactInfo: {
            email: 'contact@techsolutions.com.br',
            phone: '+55 11 3456-7890'
          },
          address: 'Av. Paulista, 1000',
          city: 'São Paulo',
          state: 'SP',
          country: 'Brazil',
          postalCode: '01310-100'
        }
      },
      attributes: {
        website: 'https://techsolutions.com.br',
        partnershipTier: 'gold'
      }
    })
  });

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

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

  response = requests.post(
      'http://api.gu1.ai/entities',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'company',
          'externalId': 'company_789',
          'name': 'Tech Solutions S.A.',
          'countryCode': 'BR',
          'taxId': '12.345.678/0001-90',
          'entityData': {
              'company': {
                  'legalName': 'Tech Solutions Sociedade Anônima',
                  'tradeName': 'Tech Solutions',
                  'incorporationDate': '2020-06-15',
                  'industry': 'Software Development',
                  'employeeCount': 50,
                  'revenue': 5000000,
                  'revenueCurrency': 'BRL',
                  'contactInfo': {
                      'email': 'contact@techsolutions.com.br',
                      'phone': '+55 11 3456-7890'
                  },
                  'address': 'Av. Paulista, 1000',
                  'city': 'São Paulo',
                  'state': 'SP',
                  'country': 'Brazil',
                  'postalCode': '01310-100'
              }
          },
          'attributes': {
              'website': 'https://techsolutions.com.br',
              'partnershipTier': 'gold'
          }
      }
  )

  entity = response.json()['entity']
  print(entity)
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "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",
    "riskScore": 35,
    "status": "active",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000,
        "revenueCurrency": "BRL"
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "partnershipTier": "gold"
    },
    "createdAt": "2024-10-03T15:00:00.000Z",
    "updatedAt": "2024-10-03T15:00:00.000Z"
  }
}
```

## Error Responses

### 400 Bad Request - Invalid Tax ID

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CNPJ format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CNPJ",
      "providedValue": "12.345.678/0001-90"
    }
  },
  "entity": null
}
```

### 400 Bad Request - Missing Required Fields

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for company creation",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}
```

### 409 Conflict - Duplicate Entity

```json theme={null}
{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "company_789",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}
```

### 401 Unauthorized

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

## Next Steps

After creating a company, you can:

1. [Get Company Details](/en/api-reference/company/get) - Retrieve complete company information
2. [List Companies](/en/api-reference/company/list) - Query your companies
3. [Update Company](/en/api-reference/company/update) - Modify company data
4. [Create KYB Validation](/use-cases/kyb/overview) - Start KYB verification process