Update Entity

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.

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).

string

Update tax identification number

string | null

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

string | null

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

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.

string

Update ISO 3166-1 alpha-2 country code

object

Update custom attributes (merges with existing attributes)

object

Update type-specific data (merges with existing entityData)

Risk matrices

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

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.

string[]

Preferred for multiple matrices: ordered list of UUIDs belonging to your organization. Send [] (or riskMatrixId: null) to remove all assignments.

Updating matrices assigns them on the entity record only; it does not run the rules engine. See Update entity by ID for full behavior and Analyze entity to evaluate rules after assignment.

Response

object

The updated entity object with all current values

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”

object

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

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

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        person: {
          income: 95000,
          occupation: 'Senior Software Engineer'
        }
      }
    })
  }
);

const result = await response.json();
console.log('Updated entity:', result.entity);
console.log('Re-evaluation triggered:', result.evaluation.id);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'person': {
                'income': 95000,
                'occupation': 'Senior Software Engineer'
            }
        }
    }
)

result = response.json()
print(f"Updated entity: {result['entity']['name']}")
print(f"Re-evaluation ID: {result['evaluation']['id']}")

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
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        company: {
          employeeCount: 75,
          revenue: 7500000
        }
      },
      attributes: {
        partnershipTier: 'platinum',
        monthlyVolume: 500000
      }
    })
  }
);

const result = await response.json();
console.log('Company updated:', result.entity.name);
console.log('New revenue:', result.entity.entityData.company.revenue);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'company': {
                'employeeCount': 75,
                'revenue': 7500000
            }
        },
        'attributes': {
            'partnershipTier': 'platinum',
            'monthlyVolume': 500000
        }
    }
)

result = response.json()
print(f"Company updated: {result['entity']['name']}")
print(f"New revenue: ${result['entity']['entityData']['company']['revenue']:,}")

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

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attributes: {
        accountTier: 'premium',
        loyaltyPoints: 15000,
        lastLoginDate: '2024-10-03T14:00:00Z'
      }
    })
  }
);

const result = await response.json();
console.log('Attributes updated:', result.entity.attributes);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'attributes': {
            'accountTier': 'premium',
            'loyaltyPoints': 15000,
            'lastLoginDate': '2024-10-03T14:00:00Z'
        }
    }
)

result = response.json()
print(f"Attributes updated: {result['entity']['attributes']}")

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
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        transaction: {
          status: 'reviewed',
          flagged: false
        }
      }
    })
  }
);

const result = await response.json();
console.log('Transaction status updated');

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'transaction': {
                'status': 'reviewed',
                'flagged': False
            }
        }
    }
)

result = response.json()
print("Transaction status updated")

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

​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