> ## 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 a person entity
> Create a new person with custom data — for person entities in the gu1 KYC and risk analysis platform, with examples for create use cases.
## Overview
Creates a new person entity with the specified attributes. Person entities represent individual customers that you want to analyze for risk and compliance (KYC).
## 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
Must be `person` for creating a person entity
Your unique identifier for this person in your system (optional but recommended)
Display name for the person
ISO 3166-1 alpha-2 country code (e.g., "US", "BR", "AR")
Tax identification number (validated based on country)
đź“‹ See [Tax ID Formats by Country](/en/api-reference/entities/tax-id-formats) for accepted formats and validation rules for each country.
Optional root **operational hours** for KYT rules (`outside_entity_operational_hours` on `transactedAt`). Same shape as [Create entity](/en/api-reference/entities/create): `timezone` + `weekly` slots. **Timezone enum:** [Transaction Time Zone Enum](/en/api-reference/transactions/time-zone-enum).
**Optional** - Custom attributes as key-value pairs for flexible metadata
Use this for custom fields that don't fit in the standard schema (e.g., internal IDs, tags, flags)
**Optional** - Person-specific data structure (see below)
**When to use entityData?**
* **Optional for basic entity creation** - You can create a person with just `type`, `name`, `taxId`, and `countryCode`
* **Required for enrichment and risk analysis** - If you want to run compliance checks, you'll need to provide relevant fields
* **Can be populated later** - You can create a minimal person first, then update it with full data before running risk analysis
**Minimal Example:**
```json theme={null}
{
"type": "person",
"name": "John Doe",
"taxId": "12345678",
"countryCode": "US"
// No entityData needed for basic creation
}
```
**Full Example (with KYC data):**
```json theme={null}
{
"type": "person",
"name": "John Doe",
"taxId": "12345678",
"countryCode": "US",
"entityData": {
"person": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1980-01-15",
"email": "john@example.com",
"phone": "+1234567890"
}
}
}
```
Person registration date in ISO 8601 datetime format (e.g., "2024-01-15T10:30:00Z")
Mark this person as a client/customer for tracking purposes
One or more risk matrix UUIDs (legacy: a single UUID string). If provided, after creation the system evaluates this person **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](#risk-matrix-execution) below.
Preferred way to pass **multiple** matrices: ordered list of UUIDs belonging to your organization. When present and non-empty, it takes precedence over `riskMatrixId`.
Skip automatic rules execution after person creation. Use this to create the entity first and manually trigger rules later.
Initial status for the person. Options:
* `active` - Person is active
* `inactive` - Person is inactive
* `blocked` - Person is blocked
* `under_review` - Person is under review (default)
* `suspended` - Person is suspended
* `expired` - Person record has expired
* `deleted` - Soft deleted
* `rejected` - Person was rejected
Configure automatic execution of enrichments when creating the person.
**Structure:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
```
**Properties:**
* `executeAllActiveEnrichments` (boolean) - Run all active org enrichments
* `enrichments` (string\[]) - Enrichment codes to run after create
* `enrichmentGroupRefs` (string\[], optional) - Marketplace group slugs
* `excludeEnrichments` (string\[], optional) - Codes to drop from the final set
`*_check` codes are no longer part of the create contract; legacy payloads that send them are ignored at parse time.
See [Person provider codes](/en/api-reference/integrations/person-provider-codes) and [Create entity](/en/api-reference/entities/create).
Optional. Only affects enrichments that support **ongoing monitoring** (today: **`global_gueno_sanctions_enrichment`**). Same semantics as [Create entity — monitoring](/en/api-reference/entities/create#example-gu1-sanctions-monitoring-on-create): `monitoring.main[code]` with `{ "watchlist": true }` (or legacy `true`), the code in `enrichments`, and org monitoring ON in Marketplace.
## Gu1 sanctions monitoring (person)
```json theme={null}
{
"type": "person",
"externalId": "cust_screening_001",
"name": "MarĂa González",
"countryCode": "AR",
"taxId": "27-12345678-1",
"entityData": {
"person": {
"firstName": "MarĂa",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR"
}
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": true
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"]
}
}
```
## Person Entity Data Structure
The `entityData.person` object should contain:
```json theme={null}
{
"person": {
"firstName": "string",
"lastName": "string",
"dateOfBirth": "YYYY-MM-DD",
"nationality": "string",
"occupation": "string",
"income": number,
"incomeCurrency": "string",
"address": "string | object (see Address Format note)",
"city": "string",
"state": "string",
"country": "string",
"postalCode": "string",
"email": "string",
"phone": "string",
"alternativePhone": "string",
"idType": "national_id | passport | drivers_license | tax_id | other",
"idNumber": "string",
"isPep": boolean,
"pepPosition": "string",
"pepCountry": "string"
}
}
```
**Address Format**: The `address` field supports both formats:
* **String format** (simple): `"Av. Paulista, 1000, SĂŁo Paulo, SP, Brazil"`
* **Object format** (structured):
```json theme={null}
{
"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 (KYC compliance rules) when creating a person by providing `riskMatrixId` or `riskMatrixIds`.
### How It Works
1. **Get your Risk Matrix ID(s)** from the gu1 dashboard (format: UUID)
2. **Include `riskMatrixId` or `riskMatrixIds` in your creation request**
3. The system will:
* Create the person entity
* Execute all KYC rules in the matrix
* Calculate risk score
* Generate compliance alerts if needed
* Update person status based on results
### Example with Risk Matrix
```json theme={null}
{
"type": "person",
"name": "MarĂa González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"person": {
"firstName": "MarĂa",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"occupation": "Software Engineer"
}
}
}
```
### Example with multiple risk matrices
```json theme={null}
{
"type": "person",
"name": "MarĂa González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixIds": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
],
"entityData": {
"person": {
"firstName": "MarĂa",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
```
### Combined with enrichments and Gu1 monitoring
Risk matrix + local enrichments + Gu1 sanctions watchlist (same pattern as [Create entity](/en/api-reference/entities/create#example-gu1-sanctions-monitoring-on-create)):
```json theme={null}
{
"type": "person",
"name": "MarĂa González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"entityData": {
"person": {
"firstName": "MarĂa",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
```
**Flow:**
1. Person is created
2. Listed enrichments run (RENAPER, REPET, Gu1 sanctions)
3. Gu1 sanctions uses **op 1** (watchlist) only when `monitoring` and Marketplace allow it
4. Risk matrix rules evaluate collected data
5. Score and alerts per rules
***
## Response
Indicates if the person was created successfully
The created person object including:
* `id` - gu1's internal ID
* `externalId` - Your external ID
* `organizationId` - Your organization ID
* `type` - Always "person"
* `name` - Person name
* `riskScore` - Initial risk score (0-100)
* `status` - Person status
* `entityData` - Person-specific data
* `attributes` - Custom attributes
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
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.
**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 `shadow` status.
## Example Request
```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,
"incomeCurrency": "USD",
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"address": "Av. Corrientes 1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina",
"postalCode": "C1043"
}
},
"attributes": {
"customerSince": "2024-01-15",
"accountType": "premium"
}
}'
```
```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,
incomeCurrency: 'USD',
email: 'maria.gonzalez@example.com',
phone: '+54 11 1234-5678',
address: 'Av. Corrientes 1234',
city: 'Buenos Aires',
state: 'CABA',
country: 'Argentina',
postalCode: 'C1043'
}
},
attributes: {
customerSince: '2024-01-15',
accountType: 'premium'
}
})
});
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,
'incomeCurrency': 'USD',
'email': 'maria.gonzalez@example.com',
'phone': '+54 11 1234-5678',
'address': 'Av. Corrientes 1234',
'city': 'Buenos Aires',
'state': 'CABA',
'country': 'Argentina',
'postalCode': 'C1043'
}
},
'attributes': {
'customerSince': '2024-01-15',
'accountType': 'premium'
}
}
)
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,
"incomeCurrency": "USD",
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"address": "Av. Corrientes 1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina",
"postalCode": "C1043"
}
},
"attributes": {
"customerSince": "2024-01-15",
"accountType": "premium"
},
"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 person creation",
"details": {
"missingFields": ["firstName", "lastName"],
"requiredFields": ["firstName", "lastName", "dateOfBirth"],
"countryCode": "AR"
}
},
"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"
}
```
## Next Steps
After creating a person, you can:
1. [Get Person Details](/en/api-reference/person/get) - Retrieve complete person information
2. [List Persons](/en/api-reference/person/list) - Query your persons
3. [Update Person](/en/api-reference/person/update) - Modify person data
4. [Create KYC Validation](/en/use-cases/kyc/create-validation) - Start KYC verification process