Update an entity by ID

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

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

PATCH

entities

{id}

Update an entity by ID

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

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

Overview

Updates an existing entity’s attributes and data. This endpoint automatically triggers a re-evaluation of the entity’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 entity to update

Request Body

All fields from the create schema are available except type (entity type cannot be changed). All fields are optional - only include the fields you want to update.

name

string

Update the entity’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). PATCH update routes ignore externalId in the body.

taxId

string

Update tax identification number

string | null

Update root-level contact email. Omit to leave unchanged; send null to clear.

phone

string | null

Update root-level contact phone. Omit to leave unchanged; send null to clear.

nationality

string | null

Root nationality (ISO 3166-1 alpha-2 when stored). Omit to leave unchanged; null clears. Updating entityData person/company nationality may refresh the root field when sent together.

countryCode

string

Update ISO 3166-1 alpha-2 country code

attributes

object

Update custom attributes (merges with existing attributes)

entityData

object

Update type-specific data (merges with existing entityData)

status

string

Entity lifecycle status (active, inactive, blocked, under_review, suspended, pending_verification, expired, rejected, deleted).Required with reason: Any status change must include reason for audit.

reason

string

Reason for the update (especially important when changing status to blocked or rejected).Required when: Changing status to blocked, rejected, or suspended.Best practice: Always provide a reason for audit trail purposes, even when not required.

changeStatusManual

boolean

default:"false"

When true, automatic status updates are disabled for this entity: risk matrix rules and automation actions such as set_entity_status do not change status. Manual updates via this endpoint (or the UI) still apply.

Default: false (rules and automations may change status when configured).
Set to false explicitly to remove the lock and allow automatic status changes again.
Does not disable risk score calculation or other rule side effects—only status writes from rules/automations.

Required with reason: if changeStatusManual changes (enable or disable), send reason in the same PATCH body for audit (same as status changes).

Risk matrices

Assign or replace which risk matrices apply to this entity. Same semantics as Create entity (riskMatrixId / riskMatrixIds).

riskMatrixId

string | string[] | null

Legacy: one UUID, an array of UUIDs, or null to clear all assigned matrices. When riskMatrixIds is sent non-empty, it takes precedence over this field.

riskMatrixIds

string[]

Preferred for multiple matrices: ordered list of UUIDs belonging to your organization. Send [] (or riskMatrixId: null) to remove all assignments. Each UUID must exist in your org; otherwise the API returns 400 with code INVALID_RISK_MATRIX.

Updating matrices assigns them on the entity record only. This endpoint does not run the rules engine or return rulesExecutionSummary. To evaluate rules after assignment, call Analyze entity or wait for lifecycle triggers (entity_created, kyc_approved, etc.) on matrices whose triggers match the event.The same body fields apply to Update by external ID and PATCH /entities/by-tax-id/{taxId}.

Response

entity

object

The updated entity 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 entity 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 an entity, 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

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 Company Information

curl -X PATCH http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "company": {
        "employeeCount": 75,
        "revenue": 7500000
      }
    },
    "attributes": {
      "partnershipTier": "platinum",
      "monthlyVolume": 500000
    }
  }'

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 Transaction Status

curl -X PATCH http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "transaction": {
        "status": "reviewed",
        "flagged": false
      }
    }
  }'

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"]
}

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 entity
const response = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  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(entity_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{entity_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()

Transaction Resolution

// Mark a flagged transaction as resolved after investigation
async function resolveTransaction(txnId, resolution) {
  const response = await fetch(`http://api.gu1.ai/entities/${txnId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        transaction: {
          status: 'resolved',
          flagged: false
        }
      },
      attributes: {
        resolutionDate: new Date().toISOString(),
        resolutionNotes: resolution,
        reviewedBy: 'compliance_team'
      }
    })
  });

  return response.json();
}

Best Practices

Partial Updates: Only send the fields you want to change - no need to send the entire entity
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 Entity - View updated entity details
List Entities - Query entities with filters
Upsert Entity - Create or update in one operation
Request AI Analysis - Get updated risk assessment

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Risk matrices

​Response

​Behavior

​Examples

​Update Person Income

​Update Company Information

​Update Custom Attributes Only

​Update Transaction Status

​Response Example

​Error Responses

​404 Not Found

​400 Bad Request - Invalid Data

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​Update After KYC Verification

​Progressive Profile Enrichment

​Transaction Resolution

​Best Practices

​Next Steps

Overview

Endpoint

Authentication

Path Parameters

Request Body

Risk matrices

Response

Behavior

Examples

Update Person Income

Update Company Information

Update Custom Attributes Only

Update Transaction Status

Response Example

Error Responses

404 Not Found

400 Bad Request - Invalid Data

401 Unauthorized

500 Internal Server Error

Use Cases

Update After KYC Verification

Progressive Profile Enrichment

Transaction Resolution

Best Practices

Next Steps