Update a person entity

Update

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

PATCH

entities

{id}

Update

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

Overview

Updates an existing person’s attributes and data. This endpoint automatically triggers a re-evaluation of the person’s risk score and emits real-time update events.

Endpoint

PATCH http://api.gu1.ai/entities/{id}

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The gu1 ID of the person to update

Request Body

All fields are optional - only include the fields you want to update.

name

string

Update the person’s display name

External ID cannot be updated with this endpoint. Use Change external ID (POST /entities/change-external-id) with a mandatory reason (min. 5 characters).

taxId

string

Update tax identification number

countryCode

string

Update ISO 3166-1 alpha-2 country code

attributes

object

Update custom attributes (merges with existing attributes)

entityData

object

Update person-specific data (merges with existing entityData)

status

string

Update person status. Available statuses:

pending - Initial state, awaiting processing
under_review - Under manual review
active - Approved and active
suspended - Temporarily suspended (requires reason)
blocked - Permanently blocked (requires reason)
rejected - Rejected during onboarding (requires reason)

Note: Status changes to suspended, blocked, or rejected require a reason field for audit purposes.

reason

string

Required when changing status to suspended, blocked, or rejected. Provides audit trail for status changes.

riskMatrixId

string

UUID of the risk matrix to associate with this person. Updates which rules are used for risk evaluation.

Response

entity

object

The updated person object with all current values

evaluation

object

Newly created evaluation triggered by the update

id - Evaluation ID
entityId - Entity ID
decision - “PENDING” (awaiting processing)
evaluationType - “SYSTEM”
reasons - Array with “Re-evaluation triggered by attribute change”

previousEntity

object

The person state before the update (for audit/comparison)

This endpoint does not return rulesResult or rulesExecutionSummary. The rules engine is not executed on update; those fields are only returned by endpoints that run rules (create, create-automatic, enrich, refresh, analyze).

Behavior

When you update a person, the system automatically:

Records the change in the entity events log with a before/after snapshot
Triggers re-evaluation to recalculate risk score based on new data
Emits real-time event to notify connected clients of the update
Maintains audit trail for compliance and review purposes

Examples

Update Person Income and Occupation

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "person": {
        "income": 95000,
        "occupation": "Senior Software Engineer"
      }
    }
  }'

Update Contact Information

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "person": {
        "email": "new.email@example.com",
        "phone": "+54 11 9876-5432",
        "address": "Av. Libertador 2500, Buenos Aires"
      }
    }
  }'

Update Custom Attributes Only

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "accountTier": "premium",
      "loyaltyPoints": 15000,
      "lastLoginDate": "2024-10-03T14:00:00Z"
    }
  }'

Update Person Status

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended",
    "reason": "Suspicious activity detected - pending investigation"
  }'

Response Example

{
  "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": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Senior Software Engineer",
        "income": 95000
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "accountTier": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T16:45:00.000Z",
    "deletedAt": null
  },
  "evaluation": {
    "id": "eval_new_123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "decision": "PENDING",
    "evaluationType": "SYSTEM",
    "reasons": ["Re-evaluation triggered by attribute change"],
    "rules": [],
    "entitySnapshot": {...}
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "person": {
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "updatedAt": "2024-10-03T14:35:00.000Z"
  }
}

Error Responses

404 Not Found

{
  "error": "Entity not found"
}

400 Bad Request - Invalid Data

{
  "error": "Validation failed",
  "details": ["Invalid country code format"]
}

400 Bad Request - Missing Reason for Status Change

{
  "error": "Changing status to 'suspended' requires a reason for audit purposes."
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to update entity"
}

Use Cases

Update After KYC Verification

// After completing KYC verification, update the person
const response = await fetch(`http://api.gu1.ai/entities/${personId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      kycVerified: true,
      kycVerificationDate: new Date().toISOString(),
      kycProvider: 'manual_review'
    }
  })
});

Progressive Profile Enrichment

# Enrich customer profile as more information becomes available
def update_customer_info(person_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{person_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'person': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()

Best Practices

Partial Updates: Only send the fields you want to change - no need to send the entire person
Monitor Re-evaluations: Check the returned evaluation ID to track risk score recalculation
Audit Trail: Use the previousEntity in the response to maintain change history
Real-time Sync: Updates emit WebSocket events for real-time UI synchronization
Idempotency: Safe to retry - updates with same data will not create duplicate events

Next Steps

Get Person - View updated person details
List Persons - Query persons with filters
Upsert Person - Create or update in one operation

List persons Update a person by external ID

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Behavior

​Examples

​Update Person Income and Occupation

​Update Contact Information

​Update Custom Attributes Only

​Update Person Status

​Response Example

​Error Responses

​404 Not Found

​400 Bad Request - Invalid Data

​400 Bad Request - Missing Reason for Status Change

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​Update After KYC Verification

​Progressive Profile Enrichment

​Best Practices

​Next Steps

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Behavior

Examples

Update Person Income and Occupation

Update Contact Information

Update Custom Attributes Only

Update Person Status

Response Example

Error Responses

404 Not Found

400 Bad Request - Invalid Data

400 Bad Request - Missing Reason for Status Change

401 Unauthorized

500 Internal Server Error

Use Cases

Update After KYC Verification

Progressive Profile Enrichment

Best Practices

Next Steps