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": {}
}API Reference
Create a company entity
Create a new company with custom data — for company entities in the gu1 risk and compliance platform, with examples for create use cases.
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 entitystring
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 activeinactive- Company is inactivenot_started- Analysis not started yet (optional initial state; default remainsunder_review)blocked- Company is blockedunder_review- Company is under review (default)pending_verification- Awaiting KYC/KYB completionawaiting_information- Waiting on client data (e.g. onboarding documents requested by email)suspended- Company is suspendedexpired- Company record has expireddeleted- Soft deletedrejected- Company was rejected
object
Configure automatic execution of enrichments when creating the company.Structure:Properties:
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_nosis_extended_verification_enrichment",
"ar_bcra_deudas_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
executeAllActiveEnrichments(boolean) - Execute all active enrichment integrations configured in your organizationenrichments(string[]) - Array of specific enrichment provider codes to execute
ValidProviderCodesEnum strings):ar_nosis_extended_verification_enrichment— NOSIS extended company enrichmentar_bcra_deudas_enrichment— BCRA debts enrichmentar_repet_entity_enrichment— REPET entity / watchlist enrichmentglobal_complyadvantage_sanctions_enrichment— ComplyAdvantage sanctions enrichmentglobal_gueno_sanctions_enrichment— Gu1 sanctions enrichment (when configured)
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
TheentityData.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 providingriskMatrixId or riskMatrixIds.
How It Works
- Get your Risk Matrix ID(s) from the gu1 dashboard (format: UUID)
- Include
riskMatrixIdorriskMatrixIdsin 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"
}
}
}
Response
boolean
Indicates if the company was created successfully
object
The created company object including:
id- gu1’s internal IDexternalId- Your external IDorganizationId- Your organization IDtype- Always “company”name- Company nameriskScore- Initial risk score (0-100)status- Company statusentityData- Company-specific dataattributes- Custom attributescreatedAt- Creation timestampupdatedAt- 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
shadowstatus.
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
Was this page helpful?