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

# Country Requirements

> Get the validation fields and document types required per country for KYC and KYB onboarding flows in the gu1 universal entity data model.

## Overview

The country requirements endpoints help developers understand what fields are required for entity creation in different countries. Each country has specific validation rules, tax ID formats, and required fields.

This eliminates trial-and-error when creating entities and provides clear guidance on what data is needed.

For **companies**, fiscal address fields (e.g. `domicilioFiscal`, `direccion`, `address`) are **optional** at creation. You can create with tax ID and legal name only, then populate the address later via manual edit or country enrichments (e.g. ARCA for Argentina).

## Supported Countries

gu1 currently supports **16 countries** with comprehensive validation:

<CardGroup cols={3}>
  <Card title="🇦🇷 Argentina" icon="flag">
    CUIT validation
  </Card>

  <Card title="🇧🇷 Brazil" icon="flag">
    CNPJ validation
  </Card>

  <Card title="🇲🇽 Mexico" icon="flag">
    RFC validation
  </Card>

  <Card title="🇨🇱 Chile" icon="flag">
    RUT validation
  </Card>

  <Card title="🇨🇴 Colombia" icon="flag">
    NIT validation
  </Card>

  <Card title="🇵🇪 Peru" icon="flag">
    RUC validation
  </Card>

  <Card title="🇺🇾 Uruguay" icon="flag">
    RUT validation
  </Card>

  <Card title="🇪🇨 Ecuador" icon="flag">
    RUC validation
  </Card>

  <Card title="🇵🇾 Paraguay" icon="flag">
    RUC validation
  </Card>

  <Card title="🇧🇴 Bolivia" icon="flag">
    NIT validation
  </Card>

  <Card title="🇻🇪 Venezuela" icon="flag">
    RIF validation
  </Card>

  <Card title="🇺🇸 United States" icon="flag">
    EIN validation
  </Card>

  <Card title="🇨🇦 Canada" icon="flag">
    BN validation
  </Card>

  <Card title="🇪🇸 Spain" icon="flag">
    CIF validation
  </Card>

  <Card title="🇵🇹 Portugal" icon="flag">
    NIPC validation
  </Card>

  <Card title="🇪🇪 Estonia" icon="flag">
    Registrikood validation
  </Card>
</CardGroup>

***

## Get All Countries

```
GET http://api.gu1.ai/entities/country-requirements
```

Retrieve a list of all supported countries.

### Response Example

```json theme={null}
{
  "success": true,
  "countries": [
    { "code": "AR", "name": "Argentina" },
    { "code": "BR", "name": "Brazil" },
    { "code": "MX", "name": "Mexico" },
    { "code": "US", "name": "United States" },
    ...
  ],
  "total": 16
}
```

***

## Get Country-Specific Requirements

```
GET http://api.gu1.ai/entities/country-requirements/:countryCode
```

Get detailed validation requirements for a specific country.

### Path Parameters

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

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="country" type="object">
  Country validation details

  <Expandable title="country properties">
    <ResponseField name="code" type="string">
      ISO country code
    </ResponseField>

    <ResponseField name="name" type="string">
      Country name
    </ResponseField>

    <ResponseField name="taxIdName" type="string">
      Local name for tax ID (e.g., "CUIT", "CNPJ", "RFC")
    </ResponseField>

    <ResponseField name="taxIdFormat" type="string">
      Regular expression pattern for tax ID validation
    </ResponseField>

    <ResponseField name="requiredFields" type="array">
      List of required attribute field names
    </ResponseField>

    <ResponseField name="optionalFields" type="array">
      List of optional attribute field names. For companies, this includes fiscal address fields that can be filled later.
    </ResponseField>

    <ResponseField name="registries" type="array">
      List of official registries for this country
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documentation" type="object">
  Example request payload

  <Expandable title="documentation properties">
    <ResponseField name="example" type="object">
      Complete example of how to create an entity for this country
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Examples

### Get Argentina Requirements

<CodeGroup>
  ```bash cURL theme={null}
  curl http://api.gu1.ai/entities/country-requirements/AR \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities/country-requirements/AR', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

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

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

  response = requests.get(
      'http://api.gu1.ai/entities/country-requirements/AR',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

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

### Response Example

```json theme={null}
{
  "success": true,
  "country": {
    "code": "AR",
    "name": "Argentina",
    "taxIdName": "CUIT",
    "taxIdFormat": "^\\d{2}-\\d{8}-\\d{1}$",
    "requiredFields": [
      "cuit",
      "razonSocial"
    ],
    "optionalFields": [
      "domicilioFiscal",
      "iibb",
      "actividadPrincipal",
      "fechaInicioActividades"
    ],
    "registries": [
      "AFIP",
      "IGJ",
      "RPC"
    ]
  },
  "documentation": {
    "example": {
      "type": "company",
      "externalId": "company_123",
      "name": "Example Company",
      "countryCode": "AR",
      "taxId": "Example CUIT",
      "attributes": {
        "cuit": "Example cuit",
        "razonSocial": "Example razonSocial",
        "domicilioFiscal": "Example domicilioFiscal"
      }
    }
  }
}
```

***

## Country-Specific Examples

### 🇦🇷 Argentina (CUIT)

```json theme={null}
{
  "type": "company",
  "externalId": "company_ar_001",
  "name": "Tech Solutions Argentina",
  "countryCode": "AR",
  "taxId": "30-71234567-8",
  "attributes": {
    "cuit": "30-71234567-8",
    "razonSocial": "Tech Solutions S.A.",
    "domicilioFiscal": "Av. Corrientes 1234, CABA",
    "iibb": "901-123456-7",
    "actividadPrincipal": "Desarrollo de Software"
  }
}
```

Minimal company creation (address optional):

```json theme={null}
{
  "type": "company",
  "externalId": "company_ar_minimal",
  "name": "Tech Solutions Argentina",
  "countryCode": "AR",
  "taxId": "30-71234567-8",
  "attributes": {
    "cuit": "30-71234567-8",
    "razonSocial": "Tech Solutions S.A."
  }
}
```

### 🇧🇷 Brazil (CNPJ)

```json theme={null}
{
  "type": "company",
  "externalId": "company_br_001",
  "name": "Tech Solutions Brasil",
  "countryCode": "BR",
  "taxId": "12.345.678/0001-90",
  "attributes": {
    "cnpj": "12.345.678/0001-90",
    "razaoSocial": "Tech Solutions Ltda",
    "enderecoFiscal": "Av. Paulista, 1000 - São Paulo, SP",
    "inscricaoEstadual": "123.456.789.012",
    "cnae": "6201-5/00"
  }
}
```

### 🇲🇽 Mexico (RFC)

```json theme={null}
{
  "type": "company",
  "externalId": "company_mx_001",
  "name": "Tech Solutions México",
  "countryCode": "MX",
  "taxId": "TSM980101ABC",
  "attributes": {
    "rfc": "TSM980101ABC",
    "razonSocial": "Tech Solutions S.A. de C.V.",
    "domicilioFiscal": "Av. Reforma 123, Ciudad de México",
    "regimenFiscal": "601"
  }
}
```

### 🇺🇸 United States (EIN)

```json theme={null}
{
  "type": "company",
  "externalId": "company_us_001",
  "name": "Tech Solutions Inc",
  "countryCode": "US",
  "taxId": "12-3456789",
  "attributes": {
    "ein": "12-3456789",
    "legalName": "Tech Solutions Inc.",
    "address": "123 Main St, San Francisco, CA 94102",
    "stateOfIncorporation": "Delaware",
    "naicsCode": "541511"
  }
}
```

### 🇪🇸 Spain (CIF)

```json theme={null}
{
  "type": "company",
  "externalId": "company_es_001",
  "name": "Tech Solutions España",
  "countryCode": "ES",
  "taxId": "A12345678",
  "attributes": {
    "cif": "A12345678",
    "razonSocial": "Tech Solutions S.L.",
    "direccionFiscal": "Calle Gran Vía 1, Madrid",
    "cnae": "6201"
  }
}
```

***

## Error Responses

### 404 - Country Not Supported

```json theme={null}
{
  "success": false,
  "error": {
    "code": "COUNTRY_NOT_SUPPORTED",
    "message": "Country code 'XX' is not supported",
    "details": {
      "countryCode": "XX",
      "supportedCountries": ["AR", "BR", "MX", ...]
    }
  }
}
```

***

## Best Practices

<AccordionGroup>
  <Accordion icon="lightbulb" title="Query Before Creating">
    Always query country requirements before creating entities to ensure you collect all necessary data from your users upfront.
  </Accordion>

  <Accordion icon="database" title="Cache Requirements">
    Country requirements rarely change. Consider caching them in your application to reduce API calls.
  </Accordion>

  <Accordion icon="shield-check" title="Validate Client-Side">
    Use the `taxIdFormat` regex pattern to validate tax IDs on the client side before submitting to the API.
  </Accordion>

  <Accordion icon="language" title="Localize Field Names">
    Display field names in the user's language. The API returns local field names (e.g., "razonSocial" for Argentina instead of "legalName").
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Entity" icon="plus" href="/api-reference/entities/create">
    Use the requirements to create a properly validated entity
  </Card>

  <Card title="Validate Tax IDs" icon="check" href="/en/api-reference/entities/country-requirements">
    Validate tax IDs before entity creation
  </Card>
</CardGroup>