Create a company entity

curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

import requests

url = "http://api.gu1.ai/entities"

payload = {
    "type": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "countryCode": "<string>",
    "taxId": "<string>",
    "operationalHours": {},
    "attributes": {},
    "entityData": {},
    "registrationDate": "<string>",
    "isClient": True,
    "riskMatrixId": ["<string>"],
    "riskMatrixIds": ["<string>"],
    "skipRulesExecution": True,
    "status": "<string>",
    "autoExecuteIntegrations": {},
    "monitoring": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    externalId: '<string>',
    name: '<string>',
    countryCode: '<string>',
    taxId: '<string>',
    operationalHours: {},
    attributes: {},
    entityData: {},
    registrationDate: '<string>',
    isClient: true,
    riskMatrixId: ['<string>'],
    riskMatrixIds: ['<string>'],
    skipRulesExecution: true,
    status: '<string>',
    autoExecuteIntegrations: {},
    monitoring: {}
  })
};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'externalId' => '<string>',
    'name' => '<string>',
    'countryCode' => '<string>',
    'taxId' => '<string>',
    'operationalHours' => [
        
    ],
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'registrationDate' => '<string>',
    'isClient' => true,
    'riskMatrixId' => [
        '<string>'
    ],
    'riskMatrixIds' => [
        '<string>'
    ],
    'skipRulesExecution' => true,
    'status' => '<string>',
    'autoExecuteIntegrations' => [
        
    ],
    'monitoring' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

Create a company entity

curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

import requests

url = "http://api.gu1.ai/entities"

payload = {
    "type": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "countryCode": "<string>",
    "taxId": "<string>",
    "operationalHours": {},
    "attributes": {},
    "entityData": {},
    "registrationDate": "<string>",
    "isClient": True,
    "riskMatrixId": ["<string>"],
    "riskMatrixIds": ["<string>"],
    "skipRulesExecution": True,
    "status": "<string>",
    "autoExecuteIntegrations": {},
    "monitoring": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    externalId: '<string>',
    name: '<string>',
    countryCode: '<string>',
    taxId: '<string>',
    operationalHours: {},
    attributes: {},
    entityData: {},
    registrationDate: '<string>',
    isClient: true,
    riskMatrixId: ['<string>'],
    riskMatrixIds: ['<string>'],
    skipRulesExecution: true,
    status: '<string>',
    autoExecuteIntegrations: {},
    monitoring: {}
  })
};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'externalId' => '<string>',
    'name' => '<string>',
    'countryCode' => '<string>',
    'taxId' => '<string>',
    'operationalHours' => [
        
    ],
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'registrationDate' => '<string>',
    'isClient' => true,
    'riskMatrixId' => [
        '<string>'
    ],
    'riskMatrixIds' => [
        '<string>'
    ],
    'skipRulesExecution' => true,
    'status' => '<string>',
    'autoExecuteIntegrations' => [
        
    ],
    'monitoring' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"operationalHours\": {},\n  \"attributes\": {},\n  \"entityData\": {},\n  \"registrationDate\": \"<string>\",\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"status\": \"<string>\",\n  \"autoExecuteIntegrations\": {},\n  \"monitoring\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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:

Authorization: Bearer YOUR_API_KEY

Request Body

string

required

Must be company for creating a company entity

string

Your unique identifier for this company in your system (optional but recommended)

string

required

Display name for the company

string

required

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

string

Tax identification number (validated based on country)

📋 See Tax ID Formats by Country for accepted formats and validation rules for each country.

object | null

Optional root operational hours for KYT rules. Same shape as Create entity.

object

Custom attributes as key-value pairs

object

required

Company-specific data structure (see below)

string

Company registration date in ISO 8601 datetime format (e.g., “2024-01-15T10:30:00Z”)

boolean

default:"false"

Mark this company as a client/customer for tracking purposes

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

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.

boolean

default:"false"

Skip automatic rules execution after company creation. Use this to create the entity first and manually trigger rules later.

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

object

Configure automatic execution of enrichments when creating the company.Structure:

{
  "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 and the full provider-codes reference.

object

Optional. Same as Create entity: 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.

Gu1 sanctions monitoring (company)

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

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

Address Format: The address field supports both formats:

String format (simple): "Av. Paulista, 1000, São Paulo, SP, Brazil"

Object format (structured):

{
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

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

Get your Risk Matrix ID(s) from the gu1 dashboard (format: UUID)
Include riskMatrixId or riskMatrixIds in your creation request
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

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

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

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

Response

boolean

Indicates if the company was created successfully

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

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.

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.

Example Request

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"
    }
  }'

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

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)

Response Example

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

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

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

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

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

Next Steps

After creating a company, you can:

Get Company Details - Retrieve complete company information
List Companies - Query your companies
Update Company - Modify company data
Create KYB Validation - Start KYB verification process

Tax ID Formats by Country Create a company automatically with enrichment

⌘I

​Overview

​Endpoint

​Authentication

​Request Body

​Gu1 sanctions monitoring (company)

​Company Entity Data Structure

​Risk Matrix Execution

​How It Works

​Example with Risk Matrix

​Example with multiple risk matrices

​Combined with enrichments and Gu1 monitoring

​Response

​Example Request

​Response Example

​Error Responses

​400 Bad Request - Invalid Tax ID

​400 Bad Request - Missing Required Fields

​409 Conflict - Duplicate Entity

​401 Unauthorized

​Next Steps

Overview

Endpoint

Authentication

Request Body

Gu1 sanctions monitoring (company)

Company Entity Data Structure

Risk Matrix Execution

How It Works

Example with Risk Matrix

Example with multiple risk matrices

Combined with enrichments and Gu1 monitoring

Response

Example Request

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

400 Bad Request - Missing Required Fields

409 Conflict - Duplicate Entity

401 Unauthorized

Next Steps