Country Requirements

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:

🇦🇷 Argentina

CUIT validation

🇧🇷 Brazil

CNPJ validation

🇲🇽 Mexico

RFC validation

🇨🇱 Chile

RUT validation

🇨🇴 Colombia

NIT validation

🇵🇪 Peru

RUC validation

🇺🇾 Uruguay

RUT validation

🇪🇨 Ecuador

RUC validation

🇵🇾 Paraguay

RUC validation

🇧🇴 Bolivia

NIT validation

🇻🇪 Venezuela

RIF validation

🇺🇸 United States

EIN validation

🇨🇦 Canada

BN validation

🇪🇸 Spain

CIF validation

🇵🇹 Portugal

NIPC validation

🇪🇪 Estonia

Registrikood validation

Get All Countries

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

Retrieve a list of all supported countries.

Response Example

{
  "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

string

required

ISO 3166-1 alpha-2 country code (e.g., “AR”, “BR”, “US”)

Response Fields

boolean

Indicates if the request was successful

object

Country validation details

Show country properties

string

ISO country code

string

Country name

string

Local name for tax ID (e.g., “CUIT”, “CNPJ”, “RFC”)

string

Regular expression pattern for tax ID validation

array

List of required attribute field names

array

List of optional attribute field names. For companies, this includes fiscal address fields that can be filled later.

array

List of official registries for this country

object

Example request payload

Show documentation properties

object

Complete example of how to create an entity for this country

Examples

Get Argentina Requirements

curl http://api.gu1.ai/entities/country-requirements/AR \
  -H "Authorization: Bearer YOUR_API_KEY"

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);

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'])

Response Example

{
  "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)

{
  "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):

{
  "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)

{
  "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)

{
  "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)

{
  "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)

{
  "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

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

Best Practices

Query Before Creating

Always query country requirements before creating entities to ensure you collect all necessary data from your users upfront.

Cache Requirements

Country requirements rarely change. Consider caching them in your application to reduce API calls.

Validate Client-Side

Use the taxIdFormat regex pattern to validate tax IDs on the client side before submitting to the API.

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”).

​Overview

​Supported Countries

🇦🇷 Argentina

🇧🇷 Brazil

🇲🇽 Mexico

🇨🇱 Chile

🇨🇴 Colombia

🇵🇪 Peru

🇺🇾 Uruguay

🇪🇨 Ecuador

🇵🇾 Paraguay

🇧🇴 Bolivia

🇻🇪 Venezuela

🇺🇸 United States

🇨🇦 Canada

🇪🇸 Spain

🇵🇹 Portugal

🇪🇪 Estonia

​Get All Countries

​Response Example

​Get Country-Specific Requirements

​Path Parameters

​Response Fields

​Examples

​Get Argentina Requirements

​Response Example

​Country-Specific Examples

​🇦🇷 Argentina (CUIT)

​🇧🇷 Brazil (CNPJ)

​🇲🇽 Mexico (RFC)

​🇺🇸 United States (EIN)

​🇪🇸 Spain (CIF)

​Error Responses

​404 - Country Not Supported

​Best Practices

​Next Steps

Create Entity

Validate Tax IDs

Overview

Supported Countries

Get All Countries

Response Example

Get Country-Specific Requirements

Path Parameters

Response Fields

Examples

Get Argentina Requirements

Response Example

Country-Specific Examples

🇦🇷 Argentina (CUIT)

🇧🇷 Brazil (CNPJ)

🇲🇽 Mexico (RFC)

🇺🇸 United States (EIN)

🇪🇸 Spain (CIF)

Error Responses

404 - Country Not Supported

Best Practices

Next Steps