Skip to main content
POST
http://api.gu1.ai
/
entities
Create
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>",
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {}
}
'
{
  "success": true,
  "entity": {}
}

​
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

​
type
string
required
Must be company for creating a company entity
​
externalId
string
required
Your unique identifier for this company in your system
​
name
string
required
Display name for the company
​
countryCode
string
required
ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)
​
taxId
string
Tax identification number (validated based on country)
📋 See Tax ID Formats by Country for accepted formats and validation rules for each country.
​
attributes
object
Custom attributes as key-value pairs
​
entityData
object
required
Company-specific data structure (see below)
​
registrationDate
string
Company registration date in ISO 8601 datetime format (e.g., “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Mark this company as a client/customer for tracking purposes
​
riskMatrixId
string
UUID of the risk matrix to execute rules from automatically. See Risk Matrix Execution section below for details.
​
skipRulesExecution
boolean
default:"false"
Skip automatic rules execution after company creation. Use this to create the entity first and manually trigger rules later.
​
status
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
  • pending_verification - Pending verification
  • expired - Company record has expired
  • deleted - Soft deleted
  • rejected - Company was rejected
​
autoExecuteIntegrations
object
Configure automatic execution of integrations (enrichments and checks) when creating the company.Structure:
{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": ["NOSIS", "REPET"],
  "checks": ["COMPLY_ADVANTAGE", "WORLDCHECK"]
}
Properties:
  • executeAllActiveEnrichments (boolean) - Execute all active enrichment integrations configured in your organization
  • executeAllActiveChecks (boolean) - Execute all active check integrations configured in your organization
  • enrichments (string[]) - Array of specific enrichment provider codes to execute
  • checks (string[]) - Array of specific check provider codes to execute
Common Provider Codes:
  • NOSIS - NOSIS Argentina (company data enrichment)
  • REPET - REPET Argentina (watchlist screening)
  • COMPLY_ADVANTAGE - ComplyAdvantage (sanctions & PEP screening)
  • WORLDCHECK - Refinitiv World-Check (compliance screening)
See Provider Codes Reference for complete list.

​
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 a risk matrix (KYB compliance rules) when creating a company by providing the riskMatrixId parameter.

​
How It Works

  1. Get your Risk Matrix ID from the gu1 dashboard (format: UUID)
  2. Include riskMatrixId in your creation request
  3. 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
    }
  }
}

​
Combined with Enrichments

For best results, combine matrix execution with automatic enrichments: 
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": ["NOSIS", "REPET"],
    "checks": ["COMPLY_ADVANTAGE"]
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}
Execution Flow:
  1. Company entity created
  2. NOSIS enrichment fetches official company data
  3. REPET checks watchlists
  4. ComplyAdvantage screens for sanctions
  5. Risk matrix rules evaluate all collected data
  6. Final risk score calculated
  7. Compliance alerts generated if rules trigger

​
Response

​
success
boolean
Indicates if the company was created successfully
​
entity
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

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

​
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:
  1. Get Company Details - Retrieve complete company information
  2. List Companies - Query your companies
  3. Update Company - Modify company data
  4. Create KYB Validation - Start KYB verification process