> ## 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 person automatically with enrichment

> Automatically create person with enriched data from registries — for person entities in the gu1 KYC and risk analysis platform, with examples for create.

## Overview

The automatic person creation endpoint allows you to create persons by providing minimal information (tax ID and country). The system automatically:

* Fetches person data from official registries
* Enriches the person with additional information
* Executes enrichments automatically

This is ideal for KYC (Know Your Customer) processes where you want to onboard customers with complete information automatically.

## Endpoint

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

## Authentication

Requires a valid API key in the Authorization header:

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

## Request Body

<ParamField body="taxId" type="string" required>
  Tax identification number of the person (e.g., CPF for Brazil, CURP for Mexico, CUIT for Argentina)

  <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="country" type="string" required>
  ISO 3166-1 alpha-2 country code (e.g., "BR", "MX", "AR", "CL")
</ParamField>

<ParamField body="type" type="string" required>
  Must be set to `person`
</ParamField>

<ParamField body="externalId" type="string">
  Your unique identifier for this person (optional, will be auto-generated if not provided)
</ParamField>

<ParamField body="isClient" type="boolean" default="false">
  Mark this person 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). After creation, active rules tied to those matrices run (unless `skipRulesExecution` is true).
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Preferred for **multiple** matrices: ordered UUID list. Takes precedence over `riskMatrixId` when non-empty.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean" default="false">
  Skip automatic rules execution after person creation
</ParamField>

<ParamField body="status" type="string" default="under_review">
  Initial status for the person
</ParamField>

<ParamField body="operationalHours" type="object | null">
  Optional **main entity** operational hours (`timezone` + `weekly`). Persisted on automatic creation the same as manual entity creation. Not applied to shareholders or relationships created via `depth`.
</ParamField>

<ParamField body="depth" type="number" default="0">
  Depth of relationship extraction (0-5). Controls how many levels of relationships to automatically fetch and create.

  * `0`: No relationships (only main entity)
  * `1`: Direct relationships only
  * `2`: Relationships + their relationships
  * `3-5`: Additional levels (use with caution - can create many entities)
</ParamField>

<ParamField body="autoExecuteIntegrations" type="object">
  Configure automatic execution of integrations for the main person entity. See [Provider Codes Reference](/en/api-reference/integrations/provider-codes) for available codes.

  **Type**: `object` (optional)

  **Properties:**

  * `executeAllActiveEnrichments` (boolean, optional, default: `false`) - Execute all active enrichment integrations
  * `enrichments` (array, optional, default: `[]`) - Array of specific enrichment provider codes to execute
  * `enrichmentGroupRefs` (array of strings, optional) - Marketplace enrichment group slugs (enrichments only). With `executeAllActiveEnrichments: false`, groups are resolved and merged with explicit `enrichments`. With `executeAllActiveEnrichments: true`, group refs are ignored (not resolved); explicit `enrichments` may still append after the active set.

  ```typescript theme={null}
  {
    executeAllActiveEnrichments?: boolean; // default: false
    enrichments?: ValidProviderCodesEnum[]; // default: []
    enrichmentGroupRefs?: string[];
  }
  ```

  **Example:**

  ```json theme={null}
  {
    "executeAllActiveEnrichments": false,
    "enrichments": ["br_bdc_basic_data_enrichment"],
    "enrichmentGroupRefs": ["my_marketplace_group_slug"],
  }
  ```
</ParamField>

<ParamField body="autoExecuteIntegrationsShareholders" type="object">
  Configure automatic execution of integrations for discovered relationships. Useful when using `depth > 0`. See [Provider Codes Reference](/en/api-reference/integrations/provider-codes) for available codes.

  **Type**: `object` (optional)

  **Properties:**

  * `executeAllActiveEnrichments` (boolean, optional, default: `false`) - Execute all active enrichments on related entities
  * `enrichments` (object, optional) - Specific enrichments by entity type
    * `company` (array, default: `[]`) - Enrichments for company relationships
    * `person` (array, default: `[]`) - Enrichments for person relationships
  * `enrichmentGroupRefs` (array of strings, optional) - Same slugs as on the main object; applied to **both** `company` and `person` when `executeAllActiveEnrichments` is `false`. When `executeAllActiveEnrichments` is `true` on this object, group refs are ignored; explicit per-type `enrichments` may still append after each side’s active set.

  ```typescript theme={null}
  {
    executeAllActiveEnrichments?: boolean;
    enrichments?: {
      company?: ValidProviderCodesEnum[];
      person?: ValidProviderCodesEnum[];
    };
    enrichmentGroupRefs?: string[];
  }
  ```

  **Example:**

  ```json theme={null}
  {
    "enrichments": {
      "person": ["br_cpfcnpj_complete_person_enrichment"],
      "company": ["br_cpfcnpj_complete_company_enrichment"]
    },
    "enrichmentGroupRefs": ["related_entities_group_slug"]
  }
  ```
</ParamField>

## Required Enrichment Codes by Country

<Warning>
  When using specific enrichment codes (not `executeAllActiveEnrichments: true`), certain enrichments are **mandatory** for the automatic creation to work. Without them, the system cannot fetch basic person data from official registries and the request will fail.
</Warning>

### Brazil (BR)

| Scenario                        | Required Enrichment Code(s)                                                       | Description                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Main entity**                 | `br_bdc_basic_data_enrichment`                                                    | Fetches person data via BDC/CPF (full name, date of birth, address, etc.)                                       |
| **Relationships** (`depth > 0`) | `br_bdc_related_companies_enrichment` **AND** `br_bdc_related_persons_enrichment` | Both required in `autoExecuteIntegrations.enrichments`. Fetches companies and persons related to the individual |

<Info>
  The relationship enrichments must be included in the **main entity's** `autoExecuteIntegrations.enrichments` array (not in `autoExecuteIntegrationsShareholders`), because the system needs to run them on the main person to discover the relationships. The `autoExecuteIntegrationsShareholders` field controls what enrichments to run **on each related entity** after they are created.
</Info>

### Argentina (AR)

| Scenario        | Required Enrichment Code                    | Description                    |
| --------------- | ------------------------------------------- | ------------------------------ |
| **Main entity** | `ar_nosis_extended_verification_enrichment` | Fetches person data from Nosis |

<Warning>
  Argentina does **not** support automatic relationship creation yet. The `depth` parameter must be `0`.
</Warning>

<ParamField body="customData" type="object">
  **Optional** — Client values for the **main person** that must not be replaced by enrichments. Full reference (root vs `entityData`): [Automatic entity creation](/en/api-reference/entities/create-automatic).

  Fields: `name`, `email`, `phone`, `birthDate` → `entityData.person.dateOfBirth`, `address` → `entityData.person.address`, `gender` (enum: `M` | `F` | `male` | `female` | `other` | `unknown` — use `other` for non-binary; see [Create entity](/en/api-reference/entities/create#person-entity)).

  **Example:**

  ```json theme={null}
  {
    "taxId": "23450679909",
    "country": "AR",
    "type": "person",
    "customData": {
      "name": "JOHN DOE",
      "email": "client@company.com",
      "phone": "+541112345678",
      "birthDate": "1990-05-15",
      "address": "123 Main St, Buenos Aires"
    }
  }
  ```
</ParamField>

<ParamField body="attributes" type="object">
  **Optional** - Custom attributes as key-value pairs for the created entity.

  Applied only to the main entity (the person created), not to relationships/shareholders. Useful for business segments, tags, internal IDs, or any metadata you want to associate at creation time.

  **Structure:** object with string keys and values of any type (string, number, boolean, array, etc.).

  **Example:**

  ```json theme={null}
  {
    "businessSegments": ["retail", "fintech"],
    "source": "onboarding_web",
    "tags": ["vip", "high_volume"]
  }
  ```
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  Complete information about the creation:

  * `entity` (object) - The person created with all data
  * `summary` (object) - Creation summary
  * `errors` (object, optional) - Details of any errors
</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 via `riskMatrixId` or `riskMatrixIds`), or null. When present, includes:

  * **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 and risk matrix was executed).** Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. Omitted when rules did not run. See [Rules Execution Summary](/en/api-reference/rules-execution-summary) for the full structure and a complete example.

  * **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>

## Examples

### Create Person with All Active Integrations

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities/automatic \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "taxId": "123.456.789-00",
      "country": "BR",
      "type": "person",
      "isClient": true,
      "autoExecuteIntegrations": {
        "executeAllActiveEnrichments": true,
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities/automatic', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      taxId: '123.456.789-00',
      country: 'BR',
      type: 'person',
      isClient: true,
      autoExecuteIntegrations: {
        executeAllActiveEnrichments: true,
      }
    })
  });

  const data = await response.json();
  console.log('Person created:', data.data.entity);
  ```

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

  response = requests.post(
      'http://api.gu1.ai/entities/automatic',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'taxId': '123.456.789-00',
          'country': 'BR',
          'type': 'person',
          'isClient': True,
          'autoExecuteIntegrations': {
              'executeAllActiveEnrichments': True,
          }
      }
  )

  data = response.json()
  print('Person created:', data['data']['entity'])
  ```
</CodeGroup>

### Create Person with Specific Integrations

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities/automatic \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "taxId": "123.456.789-00",
      "country": "BR",
      "type": "person",
      "externalId": "customer_12345",
      "autoExecuteIntegrations": {
        "enrichments": ["br_bdc_basic_data_enrichment"]
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities/automatic', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      taxId: '123.456.789-00',
      country: 'BR',
      type: 'person',
      externalId: 'customer_12345',
      autoExecuteIntegrations: {
        enrichments: ['br_bdc_basic_data_enrichment']
      }
    })
  });

  const data = await response.json();
  ```

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

  response = requests.post(
      'http://api.gu1.ai/entities/automatic',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'taxId': '123.456.789-00',
          'country': 'BR',
          'type': 'person',
          'externalId': 'customer_12345',
          'autoExecuteIntegrations': {
              'enrichments': ['br_bdc_basic_data_enrichment']
          }
      }
  )

  data = response.json()
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "entity": {
      "id": "person_uuid",
      "organizationId": "org_uuid",
      "type": "person",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "person": {
          "firstName": "João",
          "lastName": "Silva",
          "dateOfBirth": "1985-05-15",
          "nationality": "BR"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}
```

## Error Responses

### 400 Bad Request - Invalid Tax ID

```json theme={null}
{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}
```

### 404 Not Found - Person Not Found in Registry

```json theme={null}
{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}
```

### 409 Conflict - Person Already Exists

```json theme={null}
{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}
```

## Best Practices

1. **Error handling**: Always check the `success` field in the response
2. **Rate limiting**: Be mindful of rate limits when creating multiple persons
3. **Integration selection**: Choose specific integrations for better control over cost and performance

## Next Steps

* [Get Person](/en/api-reference/person/get) - Retrieve person details
* [Create Person Manually](/en/api-reference/person/create) - Create persons with your own data
* [Create KYC Validation](/en/use-cases/kyc/create-validation) - Start identity verification