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
Authentication
Requires a valid API key in the Authorization header:Request Body
Required Fields
string
required
The type of entity to create. Available types:
person- Individual person/customercompany- Business entity
string
required
Display name for the entity
string
required
ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)
string
required
Tax identification number (validated based on country)
Optional Fields
string
Your unique identifier for this entity in your system. If not provided, one will be generated automatically.
string | null
Optional primary contact email on the entity row (nullable for existing records).
string | null
Optional primary contact phone on the entity row (nullable for existing records).
string | null
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.string
Entity registration date in ISO 8601 datetime format (e.g., “2024-01-15T10:30:00Z”)
boolean
default:false
Whether this entity is a direct client of your organization
string
default:"under_review"
Initial status of the entity. Available options:
active- Entity is active and approvedinactive- Entity is inactiveblocked- Entity is blocked from operationsunder_review- Entity is under compliance review (default)suspended- Entity is temporarily suspendedexpired- Entity credentials/approval expireddeleted- Soft deleted entityrejected- Entity was rejected during review
object
Custom attributes as key-value pairs (only strings and numbers allowed)
object
Type-specific data structure. See Entity Data Structures section below.
Risk Matrix & Rules Execution
string | string[]
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.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
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 only2- Direct + nested level 23- Direct + nested levels 2-34- Direct + nested levels 2-45- Direct + nested levels 2-5 (maximum)
Risk Factors (Manual Override)
object
Manual risk factors to override automated scoring. Typically used for internal risk adjustments.Structure:
object
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
object
Automatically execute enrichment integrations upon entity creation.Structure:Options:
executeAllActiveEnrichments(boolean) - Execute all active enrichment providers configured in your organizationenrichments(string[]) - Array of specific enrichment provider codes to executeenrichmentGroupRefs(string[], 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.
ValidProviderCodesEnum string values):ar_nosis_extended_verification_enrichment— NOSIS extended company enrichmentar_bcra_deudas_enrichment— BCRA debts enrichmentglobal_complyadvantage_sanctions_enrichment— ComplyAdvantage sanctions screeningglobal_gueno_sanctions_enrichment— Gu1 sanctions screening (when configured)
Entity Data Structures
Person Entity
Complete schema for person/individual entities (KYC):Company Entity
Complete schema for company/business entities (KYB):Transaction Entity
Complete schema for transaction entities (fraud detection & AML):Device Entity
Complete schema for device entities (device fingerprinting):Payment Method Entity
Complete schema for payment method entities:Location Entity
Complete schema for location/address entities:Document Entity
Complete schema for document entities:Alert Entity
Complete schema for alert entities:Generic Address Field
For country-specific address requirements, you can also use the genericaddress field:
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 providingriskMatrixId or riskMatrixIds.
How It Works
- Create your risk matrix in the gu1 dashboard or via API
- Get the Matrix ID(s) (UUID format:
550e8400-e29b-41d4-a716-446655440000) - Include
riskMatrixIdorriskMatrixIdsin your entity creation request - 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
Example: Create company with multiple risk matrices
What Happens After Execution
After the matrix executes, the entity response will include:Matrix Execution Options
Skip Rules Execution
If you want to create the entity but delay rule execution:/entities/{id}/execute-rules endpoint.
Without Matrix ID
If you don’t provideriskMatrixId 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:- Entity is created
- Enrichments execute (per your
autoExecuteIntegrations/ org config, e.g.ar_nosis_extended_verification_enrichment) - Risk matrix rules evaluate against enriched data
- Final risk score calculated
- Alerts generated if rules trigger
Response
boolean
Indicates if the entity was created successfully
object
The created entity object including:
id- gu1’s internal IDexternalId- Your external IDorganizationId- Your organization IDtype- Entity typename- Entity nameriskScore- Initial risk score (0-100)status- Entity statusentityData- Type-specific dataattributes- Custom attributescreatedAt- Creation timestampupdatedAt- Last update timestamp
Examples
Create Person Entity (KYC)
Create Company Entity (KYB)
Create Transaction Entity (Fraud Detection)
Response Example
Error Responses
400 Bad Request - Invalid Tax ID
400 Bad Request - Missing Required Fields
409 Conflict - Duplicate Entity
401 Unauthorized
429 Too Many Requests
500 Internal Server Error
Next Steps
After creating an entity, you can:- Request AI Analysis - Get automated risk assessment
- List Entities - Query your entities
- Get Entity Details - Retrieve complete entity information
- Apply Rules - Run compliance and risk rules