> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Entity
> Create a new entity in gu1 by sending company, person, or transaction data so it can be enriched, scored, and monitored across your workflows.
## Overview
Creates a new entity with the specified type and attributes. Entities represent the core data objects you want to analyze for risk and compliance.
## Endpoint
```
POST http://api.gu1.ai/entities
```
## Authentication
Requires a valid API key in the Authorization header:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Request Body
### Required Fields
The type of entity to create. Available types:
* `person` - Individual person/customer
* `company` - Business entity
Display name for the entity
ISO 3166-1 alpha-2 country code (e.g., "US", "BR", "AR")
Tax identification number (validated based on country)
### Optional Fields
Your unique identifier for this entity in your system. If not provided, one will be generated automatically.
Optional primary contact email on the entity row (nullable for existing records).
Optional primary contact phone on the entity row (nullable for existing records).
Optional root-level nationality: ISO 3166-1 alpha-2, or a recognized label the API maps to ISO2. If omitted, the root field may still be derived from `entityData.person.nationality` or `entityData.company.nationality` when mappable.
Entity registration date in ISO 8601 datetime format (e.g., "2024-01-15T10:30:00Z")
Whether this entity is a direct client of your organization
Initial status of the entity. Available options:
* `active` - Entity is active and approved
* `inactive` - Entity is inactive
* `blocked` - Entity is blocked from operations
* `under_review` - Entity is under compliance review (default)
* `suspended` - Entity is temporarily suspended
* `expired` - Entity credentials/approval expired
* `deleted` - Soft deleted entity
* `rejected` - Entity was rejected during review
Custom attributes as key-value pairs (only strings and numbers allowed)
Type-specific data structure. See [Entity Data Structures](#entity-data-structures) section below.
### Risk Matrix & Rules Execution
One or more risk matrix UUIDs (legacy: a single UUID string). If provided, after creation the system evaluates this entity **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.
Preferred way to pass **multiple** matrices: ordered list of UUIDs belonging to your organization. When present and non-empty, it takes precedence over `riskMatrixId`.
Set to `true` to skip automatic rules execution after entity creation. Use this when you want to manually trigger rule evaluation later.
**For company entities only:** How many levels of shareholders to auto-create when creating a company.
* `0` - None (default)
* `1` - Direct shareholders only
* `2` - Direct + nested level 2
* `3` - Direct + nested levels 2-3
* `4` - Direct + nested levels 2-4
* `5` - Direct + nested levels 2-5 (maximum)
### Risk Factors (Manual Override)
Manual risk factors to override automated scoring. Typically used for internal risk adjustments.
**Structure:**
```json theme={null}
{
"reasons": ["string array of risk reasons"],
"customLabel": {
"name": "Custom Risk Label",
"color": "#ff0000",
"status": "high_risk",
"minScore": 80,
"maxScore": 100,
"severity": "high" // low | medium | high | critical
},
"displayRange": {
"min": 0,
"max": 100,
"current": 85,
"isInfinite": false
},
"originalScore": 85,
"normalizedScore": 85
}
```
Optional: per-integration booleans under `main` so an enrichment can run in watchlist mode (Regtia op 1) for the **main** entity when listed in `autoExecuteIntegrations`. Requires org-level monitoring enabled for that integration in Marketplace (e.g. `global_gueno_sanctions_enrichment`). The `relationships` key is only used by `POST /entities/automatic` with depth.
Example: `{ "main": { "global_gueno_sanctions_enrichment": true } }`
### Auto-Execute Integrations
Automatically execute enrichment integrations upon entity creation.
**Structure:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_nosis_extended_verification_enrichment",
"ar_bcra_deudas_enrichment",
"global_complyadvantage_sanctions_enrichment",
"global_gueno_sanctions_enrichment"
]
}
```
**Options:**
* `executeAllActiveEnrichments` (boolean) - Execute all active enrichment providers configured in your organization
* `enrichments` (string\[]) - Array of specific enrichment provider codes to execute
* `enrichmentGroupRefs` (string\[], optional) - Marketplace enrichment group slugs (enrichments only). With `executeAllActiveEnrichments: false`, groups are resolved and merged with explicit `enrichments`. With `executeAllActiveEnrichments: true`, group refs are ignored (not resolved); explicit `enrichments` may still append after the active set.
Legacy `*_check` provider codes in `enrichments` are **silently ignored** (removed from the request). Use the matching `*_enrichment` code instead.
**Example provider codes (Argentina company — must match `ValidProviderCodesEnum` string values):**
* `ar_nosis_extended_verification_enrichment` — NOSIS extended company enrichment
* `ar_bcra_deudas_enrichment` — BCRA debts enrichment
* `global_complyadvantage_sanctions_enrichment` — ComplyAdvantage sanctions screening
* `global_gueno_sanctions_enrichment` — Gu1 sanctions screening (when configured)
See [Provider codes reference](/en/api-reference/integrations/provider-codes) for the full list.
## Entity Data Structures
### Person Entity
Complete schema for person/individual entities (KYC):
```json theme={null}
{
"person": {
"firstName": "string (optional)",
"lastName": "string (optional)",
"dateOfBirth": "string (optional) - Format: YYYY-MM-DD",
"nationality": "string (optional) - ISO 3166-1 alpha-2 country code",
"occupation": "string (optional)",
"income": "number (optional)",
"incomeCurrency": "string (optional) - ISO 4217 currency code",
// Address - can be string or structured object
"address": "string | object (optional)",
// If object format:
"address": {
"street": "string (optional)",
"number": "string (optional)",
"complement": "string (optional)",
"neighborhood": "string (optional)",
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)"
},
// Alternative: individual address fields
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)",
// Contact information
"email": "string (optional)",
"phone": "string (optional)",
"alternativePhone": "string (optional)",
// Identification
"idType": "national_id | passport | drivers_license | tax_id | other (optional)",
"idNumber": "string (optional)",
// PEP (Politically Exposed Person) screening
"isPep": "boolean (optional)",
"pepPosition": "string (optional) - e.g., 'Minister of Finance'",
"pepCountry": "string (optional) - ISO 3166-1 alpha-2 country code"
}
}
```
### Company Entity
Complete schema for company/business entities (KYB):
```json theme={null}
{
"company": {
"legalName": "string (optional)",
"tradeName": "string (optional)",
"incorporationDate": "string (optional) - Format: YYYY-MM-DD",
"companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other (optional)",
"industry": "string (optional)",
"websiteUrl": "string (optional)",
"employeeCount": "number (optional)",
"revenue": "number (optional)",
"revenueCurrency": "string (optional) - ISO 4217 currency code",
// Contact information
"contactInfo": {
"email": "string (optional)",
"phone": "string (optional)",
"alternativePhone": "string (optional)"
},
// Address - can be string or structured object
"address": "string | object (optional)",
// If object format:
"address": {
"street": "string (optional)",
"number": "string (optional)",
"complement": "string (optional)",
"neighborhood": "string (optional)",
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)"
},
// Alternative: individual address fields
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)"
}
}
```
### Transaction Entity
Complete schema for transaction entities (fraud detection & AML):
```json theme={null}
{
"transaction": {
"transactionId": "string (optional)",
"type": "string (optional) - e.g., wire_transfer, card_payment, crypto_transfer",
"status": "string (optional) - e.g., pending, completed, failed, cancelled",
"amount": "number (optional)",
"currency": "string (optional) - ISO 4217 currency code",
"paymentMethod": "string (optional) - e.g., bank_transfer, credit_card, pix, crypto",
"originEntityId": "string (optional) - Sender entity ID",
"destinationEntityId": "string (optional) - Recipient entity ID",
"transactedAt": "string (optional) - ISO 8601 timestamp",
"riskScore": "number (optional) - Manual risk score override",
"flagged": "boolean (optional) - Manual flag",
"category": "string (optional) - Transaction category/purpose",
"description": "string (optional) - Transaction description"
}
}
```
### Device Entity
Complete schema for device entities (device fingerprinting):
```json theme={null}
{
"device": {
"type": "string (optional) - e.g., mobile, tablet, desktop, pos_terminal",
"model": "string (optional) - Device model",
"manufacturer": "string (optional) - Device manufacturer",
"serialNumber": "string (optional) - Device serial number",
"os": "string (optional) - Operating system",
"lastSeen": "string (optional) - ISO 8601 timestamp",
"imei": "string (optional) - International Mobile Equipment Identity",
"carrier": "string (optional) - Mobile carrier/network operator",
"phoneNumber": "string (optional) - Associated phone number"
}
}
```
### Payment Method Entity
Complete schema for payment method entities:
```json theme={null}
{
"paymentMethod": {
"type": "string (optional) - e.g., credit_card, debit_card, bank_account, pix, crypto_wallet",
"issuer": "string (optional) - Card issuer or bank name",
"lastFour": "string (optional) - Last 4 digits of card/account",
"expiryDate": "string (optional) - Card expiry date (MM/YY)",
"isDefault": "boolean (optional) - Is this the default payment method",
"pixKey": "string (optional) - PIX key (Brazil)",
"pixKeyType": "string (optional) - PIX key type: email, cpf, cnpj, phone, random",
"bankName": "string (optional) - Bank name",
"bankCode": "string (optional) - Bank code/routing number"
}
}
```
### Location Entity
Complete schema for location/address entities:
```json theme={null}
{
"location": {
"type": "string (optional) - e.g., residence, business, branch, atm, registered_office",
// Address - can be string or structured object
"address": "string | object (optional)",
// If object format:
"address": {
"street": "string (optional)",
"number": "string (optional)",
"complement": "string (optional)",
"neighborhood": "string (optional)",
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)"
},
// Alternative: individual address fields
"city": "string (optional)",
"state": "string (optional)",
"postalCode": "string (optional)",
// Geographic coordinates
"coordinates": {
"lat": "number (required if coordinates provided)",
"lng": "number (required if coordinates provided)"
}
}
}
```
### Document Entity
Complete schema for document entities:
```json theme={null}
{
"document": {
"type": "string (optional) - e.g., passport, id_card, drivers_license, tax_certificate, incorporation_doc",
"issuer": "string (optional) - Document issuing authority",
"issueDate": "string (optional) - ISO 8601 date",
"expiryDate": "string (optional) - ISO 8601 date",
"documentNumber": "string (optional) - Document identification number"
}
}
```
### Alert Entity
Complete schema for alert entities:
```json theme={null}
{
"alert": {
"alertNumber": "string (optional) - Unique alert identifier",
"alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM (optional)",
"severity": "INFO | WARNING | HIGH | CRITICAL (optional)",
"status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE (optional)",
"sourceSystem": "string (optional) - System that generated the alert",
"triggerRuleId": "string (optional) - Rule ID that triggered the alert",
"triggerCondition": "string (optional) - Condition description",
"affectedEntityId": "string (optional) - Primary entity affected",
"relatedEntityIds": "string[] (optional) - Related entities",
"alertedAt": "string (optional) - ISO 8601 timestamp when alert was generated",
"acknowledgedAt": "string (optional) - ISO 8601 timestamp when acknowledged",
"acknowledgedBy": "string (optional) - User who acknowledged",
"resolvedAt": "string (optional) - ISO 8601 timestamp when resolved",
"resolvedBy": "string (optional) - User who resolved",
"resolutionNotes": "string (optional) - Resolution notes",
"falsePositiveReason": "string (optional) - Reason if marked as false positive"
}
}
```
### Generic Address Field
For country-specific address requirements, you can also use the generic `address` field:
```json theme={null}
{
"address": {
"street": "string (optional)",
"city": "string (optional)",
"state": "string (optional)",
"country": "string (optional)",
"postalCode": "string (optional)",
"number": "string (optional)",
"complement": "string (optional)",
"neighborhood": "string (optional)"
}
}
```
***
## Risk Matrix Execution on Entity Creation
You can automatically execute one or more risk matrices (set of compliance and risk rules) when creating an entity by providing `riskMatrixId` or `riskMatrixIds`.
### How It Works
1. **Create your risk matrix** in the gu1 dashboard or via API
2. **Get the Matrix ID(s)** (UUID format: `550e8400-e29b-41d4-a716-446655440000`)
3. **Include `riskMatrixId` or `riskMatrixIds` in your entity creation request**
4. The system will automatically:
* Create the entity
* Execute all rules in the specified matrix
* Calculate risk scores
* Generate alerts if rules are triggered
* Update entity status based on results
### Example: Create Company with Risk Matrix
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "30-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"company": {
"legalName": "Tech Solutions Sociedade Anônima",
"tradeName": "Tech Solutions",
"incorporationDate": "2020-06-15",
"industry": "fintech",
"revenue": 5000000
}
}
}
```
### Example: Create company with multiple risk matrices
```json theme={null}
{
"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 Sociedade Anônima",
"industry": "fintech"
}
}
}
```
### What Happens After Execution
After the matrix executes, the entity response will include:
```json theme={null}
{
"success": true,
"entity": {
"id": "entity-uuid-here",
"name": "Tech Solutions S.A.",
"riskScore": 75,
"status": "under_review",
"riskFactors": {
"originalScore": 75,
"normalizedScore": 75,
"reasons": [
"High-risk industry detected",
"Company in high-risk jurisdiction"
],
"displayRange": {
"min": 50,
"max": 79,
"current": 75,
"isInfinite": false
},
"customLabel": {
"name": "⚠️ Medio Riesgo",
"color": "#f59e0b",
"status": "under_review",
"minScore": 50,
"maxScore": 79,
"severity": "medium"
}
}
},
"alerts": [
{
"id": "alert-uuid",
"severity": "WARNING",
"message": "Company operates in fintech industry - requires enhanced due diligence",
"ruleId": "rule-industry-check"
}
]
}
```
### Matrix Execution Options
#### Skip Rules Execution
If you want to create the entity but delay rule execution:
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"skipRulesExecution": true,
"entityData": { ... }
}
```
You can manually trigger rule execution later using the `/entities/{id}/execute-rules` endpoint.
#### Without Matrix ID
If you don't provide `riskMatrixId` or `riskMatrixIds`, the system will:
* Use your organization's default matrix (if configured)
* Or skip rule execution entirely
### Combined with Auto-Execute Integrations
You can combine matrix execution with automatic enrichments:
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "30-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": true,
"enrichments": [
"global_complyadvantage_sanctions_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"entityData": {
"company": {
"legalName": "Tech Solutions Sociedade Anônima",
"industry": "fintech"
}
}
}
```
**Execution Order:**
1. Entity is created
2. Enrichments execute (per your `autoExecuteIntegrations` / org config, e.g. `ar_nosis_extended_verification_enrichment`)
3. Risk matrix rules evaluate against enriched data
4. Final risk score calculated
5. Alerts generated if rules trigger
***
## Response
Indicates if the entity was created successfully
The created entity object including:
* `id` - gu1's internal ID
* `externalId` - Your external ID
* `organizationId` - Your organization ID
* `type` - Entity type
* `name` - Entity name
* `riskScore` - Initial risk score (0-100)
* `status` - Entity status
* `entityData` - Type-specific data
* `attributes` - Custom attributes
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
## Examples
### Create Person Entity (KYC)
```bash cURL theme={null}
curl -X POST http://api.gu1.ai/entities \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "person",
"externalId": "customer_12345",
"name": "María González",
"countryCode": "AR",
"taxId": "20-12345678-9",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000
}
},
"attributes": {
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"customerSince": "2024-01-15"
}
}'
```
```javascript JavaScript theme={null}
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: 'person',
externalId: 'customer_12345',
name: 'María González',
countryCode: 'AR',
taxId: '20-12345678-9',
entityData: {
person: {
firstName: 'María',
lastName: 'González',
dateOfBirth: '1985-03-15',
nationality: 'AR',
occupation: 'Software Engineer',
income: 85000
}
},
attributes: {
email: 'maria.gonzalez@example.com',
phone: '+54 11 1234-5678',
customerSince: '2024-01-15'
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'type': 'person',
'externalId': 'customer_12345',
'name': 'María González',
'countryCode': 'AR',
'taxId': '20-12345678-9',
'entityData': {
'person': {
'firstName': 'María',
'lastName': 'González',
'dateOfBirth': '1985-03-15',
'nationality': 'AR',
'occupation': 'Software Engineer',
'income': 85000
}
},
'attributes': {
'email': 'maria.gonzalez@example.com',
'phone': '+54 11 1234-5678',
'customerSince': '2024-01-15'
}
}
)
entity = response.json()['entity']
print(entity)
```
### Create Company Entity (KYB)
```bash cURL theme={null}
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
}
},
"attributes": {
"website": "https://techsolutions.com.br",
"registeredAddress": "Av. Paulista, 1000, São Paulo",
"partnershipTier": "gold"
}
}'
```
```javascript JavaScript theme={null}
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
}
},
attributes: {
website: 'https://techsolutions.com.br',
registeredAddress: 'Av. Paulista, 1000, São Paulo',
partnershipTier: 'gold'
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
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
}
},
'attributes': {
'website': 'https://techsolutions.com.br',
'registeredAddress': 'Av. Paulista, 1000, São Paulo',
'partnershipTier': 'gold'
}
}
)
entity = response.json()['entity']
print(entity)
```
### Create Transaction Entity (Fraud Detection)
```bash cURL theme={null}
curl -X POST http://api.gu1.ai/entities \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "transaction",
"externalId": "txn_98765",
"name": "Wire Transfer - $50,000",
"countryCode": "US",
"entityData": {
"transaction": {
"transactionId": "txn_98765",
"type": "wire_transfer",
"status": "completed",
"amount": 50000,
"currency": "USD",
"paymentMethod": "bank_transfer",
"originEntityId": "customer_12345",
"destinationEntityId": "merchant_456",
"transactedAt": "2024-10-03T14:30:00Z",
"category": "business_payment",
"description": "Payment for professional services"
}
}
}'
```
```javascript JavaScript theme={null}
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: 'transaction',
externalId: 'txn_98765',
name: 'Wire Transfer - $50,000',
countryCode: 'US',
entityData: {
transaction: {
transactionId: 'txn_98765',
type: 'wire_transfer',
status: 'completed',
amount: 50000,
currency: 'USD',
paymentMethod: 'bank_transfer',
originEntityId: 'customer_12345',
destinationEntityId: 'merchant_456',
transactedAt: '2024-10-03T14:30:00Z',
category: 'business_payment',
description: 'Payment for professional services'
}
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'type': 'transaction',
'externalId': 'txn_98765',
'name': 'Wire Transfer - $50,000',
'countryCode': 'US',
'entityData': {
'transaction': {
'transactionId': 'txn_98765',
'type': 'wire_transfer',
'status': 'completed',
'amount': 50000,
'currency': 'USD',
'paymentMethod': 'bank_transfer',
'originEntityId': 'customer_12345',
'destinationEntityId': 'merchant_456',
'transactedAt': '2024-10-03T14:30:00Z',
'category': 'business_payment',
'description': 'Payment for professional services'
}
}
}
)
entity = response.json()['entity']
print(entity)
```
## Response Example
```json theme={null}
{
"success": true,
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "customer_12345",
"organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskScore": 25,
"status": "active",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000
}
},
"attributes": {
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"customerSince": "2024-01-15"
},
"createdAt": "2024-10-03T14:30:00.000Z",
"updatedAt": "2024-10-03T14:30:00.000Z"
}
}
```
## Error Responses
### 400 Bad Request - Invalid Tax ID
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid CUIT format. Please check the format and try again.",
"details": {
"field": "taxId",
"taxIdName": "CUIT",
"providedValue": "20-12345678-9"
}
},
"entity": null
}
```
### 400 Bad Request - Missing Required Fields
```json theme={null}
{
"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
```json theme={null}
{
"success": false,
"error": {
"code": "DUPLICATE_ENTITY",
"message": "Entity with this external_id already exists",
"details": {
"field": "external_id",
"value": "customer_12345",
"constraint": "entities_organization_external_id_unique"
}
},
"entity": null
}
```
### 401 Unauthorized
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
### 429 Too Many Requests
```json theme={null}
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded your API rate limit. Please wait before making more requests.",
"retryAfter": 3600,
"limit": 100,
"remaining": 0,
"resetAt": "2025-01-15T10:00:00Z"
}
```
### 500 Internal Server Error
```json theme={null}
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred while creating the entity",
"details": {
"message": "Database connection timeout"
}
},
"entity": null
}
```
## Next Steps
After creating an entity, you can:
1. [Request AI Analysis](/en/api-reference/entities/analyze) - Get automated risk assessment
2. [List Entities](/api-reference/entities/list) - Query your entities
3. [Get Entity Details](/api-reference/entities/get) - Retrieve complete entity information
4. [Apply Rules](/en/api-reference/rules/execute) - Run compliance and risk rules