Create a company automatically with enrichment
curl --request POST \
--url http://api.gu1.ai/entities/automatic \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"externalId": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"depth": 123,
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"externalId": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"depth": 123,
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
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({
taxId: '<string>',
country: '<string>',
type: '<string>',
externalId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
depth: 123,
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', 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/automatic",
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([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'externalId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'depth' => 123,
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
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/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\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/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
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 \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}API Reference
Create a company automatically with enrichment
Automatically create company with enriched data from registries β for company entities in the gu1 risk and compliance platform, with examples for create.
POST
/
entities
/
automatic
Create a company automatically with enrichment
curl --request POST \
--url http://api.gu1.ai/entities/automatic \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"externalId": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"depth": 123,
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"externalId": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"depth": 123,
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
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({
taxId: '<string>',
country: '<string>',
type: '<string>',
externalId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
depth: 123,
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', 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/automatic",
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([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'externalId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'depth' => 123,
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
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/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\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/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
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 \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}Overview
The automatic company creation endpoint allows you to create companies by providing minimal information (tax ID and country). The system automatically:- Fetches company data from official registries
- Enriches the company with additional information
- Executes enrichments automatically
Endpoint
POST http://api.gu1.ai/entities/automatic
Authentication
Requires a valid API key in the Authorization header:Authorization: Bearer YOUR_API_KEY
Request Body
string
required
Tax identification number of the company (e.g., CPF for Brazil, CURP for Mexico, CUIT for Argentina)
π See Tax ID Formats by Country for accepted formats and validation rules for each country.
string
required
ISO 3166-1 alpha-2 country code (e.g., βBRβ, βMXβ, βARβ, βCLβ)
string
required
Must be set to
companystring
Your unique identifier for this company (optional, will be auto-generated if not provided)
boolean
default:"false"
Mark this company as a client/business for tracking purposes
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).string[]
Preferred for multiple matrices: ordered UUID list. Takes precedence over
riskMatrixId when non-empty.boolean
default:"false"
Skip automatic rules execution after company creation
string
default:"under_review"
Initial status. Default
under_review. Optional: not_started, active, inactive, blocked, under_review, pending_verification, awaiting_information, suspended, expired, deleted, rejected. See Entities overview β Entity Status.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.number
default:"0"
Depth of relationship extraction (0-5). Controls how many levels of shareholders/relationships to automatically fetch and create.
0: No relationships (only main entity)1: Direct shareholders only2: Shareholders + their shareholders3-5: Additional levels (use with caution - can create many entities)
object
Configure automatic execution of integrations for the main company entity. See Provider Codes Reference for available codes.Type: Example:
object (optional)Properties:executeAllActiveEnrichments(boolean, optional, default:false) - Execute all active enrichment integrationsenrichments(array, optional, default:[]) - Array of specific enrichment provider codes to executeenrichmentGroupRefs(array of strings, optional) - Marketplace enrichment group slugs (enrichments only). WithexecuteAllActiveEnrichments: false, groups are resolved and merged with explicitenrichments. WithexecuteAllActiveEnrichments: true, group refs are ignored (not resolved); explicitenrichmentsmay still append after the active set.
{
executeAllActiveEnrichments?: boolean; // default: false
enrichments?: ValidProviderCodesEnum[]; // default: []
enrichmentGroupRefs?: string[];
}
{
"executeAllActiveEnrichments": false,
"enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"],
}
object
Configure automatic execution of integrations for discovered shareholders/relationships. Useful when using Example:
depth > 0. See Provider Codes Reference for available codes.Type: object (optional)Properties:executeAllActiveEnrichments(boolean, optional, default:false) - Execute all active enrichments on shareholdersenrichments(object, optional) - Specific enrichments by entity typecompany(array, default:[]) - Enrichments for company shareholdersperson(array, default:[]) - Enrichments for person shareholders
enrichmentGroupRefs(array of strings, optional) - Same slugs as on the main object; applied to bothcompanyandpersonwhenexecuteAllActiveEnrichmentsisfalse. WhenexecuteAllActiveEnrichmentsistrueon this object, group refs are ignored; explicit per-typeenrichmentsmay still append after each sideβs active set.
{
executeAllActiveEnrichments?: boolean;
enrichments?: {
company?: ValidProviderCodesEnum[];
person?: ValidProviderCodesEnum[];
};
enrichmentGroupRefs?: string[];
}
{
"enrichments": {
"person": [
"br_cpfcnpj_complete_person_enrichment",
"global_complyadvantage_person_search_enrichment"
],
"company": ["br_cpfcnpj_complete_company_enrichment"]
},
"enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}
Required Enrichment Codes by Country
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 company data from official registries and the request will fail.Brazil (BR)
| Scenario | Required Enrichment Code(s) | Description |
|---|---|---|
| Main entity | br_cpfcnpj_complete_company_enrichment | Fetches company data from CNPJ/Receita Federal (legal name, trade name, address, industry, etc.) |
Shareholders (depth > 0) | br_bdc_shareholders_enrichment | Required in autoExecuteIntegrations.enrichments. Fetches the QSA (Quadro SocietΓ‘rio) to discover company shareholders and directors |
The shareholder enrichment must be included in the main entityβs
autoExecuteIntegrations.enrichments array (not in autoExecuteIntegrationsShareholders), because the system needs to run it on the main company to discover the QSA. The autoExecuteIntegrationsShareholders field controls what enrichments to run on each shareholder after they are created.Argentina (AR)
| Scenario | Required Enrichment Code | Description |
|---|---|---|
| Main entity | ar_nosis_extended_verification_enrichment | Fetches company data from Nosis (legal name, CUIT status, address, activities, etc.) |
Argentina does not support automatic shareholder creation yet. The
depth parameter must be 0. If depth > 0 is provided, the request will fail with an error.object
Optional β Client values for the main company that must not be replaced by enrichments. Full reference: Automatic entity creation.Fields:
name, email, phone, address β entityData.company.address (birthDate is not used for companies).Example:{
"taxId": "30712345678",
"country": "AR",
"type": "company",
"customData": {
"name": "Acme Argentina S.A. (trade name)",
"email": "contact@acme.com",
"phone": "+541140000000",
"address": { "fullAddress": "Av. del Libertador 100, Buenos Aires", "city": "Buenos Aires" }
}
}
object
Optional - Custom attributes as key-value pairs for the created entity.Applied only to the main entity (the company created), not to shareholders/relationships. 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:
{
"businessSegments": ["retail", "fintech"],
"source": "onboarding_web",
"tags": ["vip", "high_volume"]
}
Response
boolean
Indicates if the company was created successfully
object
Complete information about the creation:
entity(object) - The company created with all datasummary(object) - Creation summaryerrors(object, optional) - Details of any errors
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.
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 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
shadowstatus.
Examples
Create Company with All Active Integrations
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": "company",
"isClient": true,
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": true,
}
}'
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: 'company',
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log('Company created:', data.data.entity);
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': 'company',
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print('Company created:', data['data']['entity'])
Create Company with Specific Integrations
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": "company",
"externalId": "business_12345",
"autoExecuteIntegrations": {
"enrichments": ["br_cpfcnpj_complete_company_enrichment"],
}
}'
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: 'company',
externalId: 'business_12345',
autoExecuteIntegrations: {
enrichments: ['br_cpfcnpj_complete_company_enrichment'],
}
})
});
const data = await response.json();
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': 'company',
'externalId': 'business_12345',
'autoExecuteIntegrations': {
'enrichments': ['br_cpfcnpj_complete_company_enrichment'],
}
}
)
data = response.json()
Response Example
{
"success": true,
"data": {
"entity": {
"id": "company_uuid",
"organizationId": "org_uuid",
"type": "company",
"name": "Tech Solutions LTDA",
"taxId": "12345678900",
"countryCode": "BR",
"status": "under_review",
"entityData": {
"company": {
"legalName": "Tech Solutions LTDA",
"tradeName": "Tech Solutions",
"incorporationDate": "2020-01-15",
"industry": "Technology"
}
},
"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
{
"success": false,
"error": "Invalid CPF format for Brazil"
}
404 Not Found - Company Not Found in Registry
{
"success": false,
"error": "Entity not found in official registry",
"details": {
"taxId": "123.456.789-00",
"country": "BR",
"registry": "Receita Federal"
}
}
409 Conflict - Company Already Exists
{
"success": false,
"error": "Entity with this tax ID already exists",
"details": {
"existingEntityId": "uuid",
"taxId": "123.456.789-00"
}
}
Best Practices
- Error handling: Always check the
successfield in the response - Rate limiting: Be mindful of rate limits when creating multiple companies
- Integration selection: Choose specific integrations for better control over cost and performance
Next Steps
- Get Company - Retrieve company details
- Create Company Manually - Create companies with your own data
- Create KYB Validation - Start identity verification
Was this page helpful?