Update Entity by External ID

Overview

This endpoint allows you to update an entity using your own external identifier instead of our internal UUID. This is useful when you don’t store our UUIDs in your system and only track your own external IDs. The functionality is identical to PATCH /entities/:id, but uses externalId as the identifier.

Path Parameters

externalId

string

required

Your unique external identifier for the entity

Request Body

name

string

Entity name (person full name or company name)

taxId

string

Tax identification number (SSN, EIN, VAT, RFC, etc.)

status

string

Entity status. Possible values:

active: Entity is active and operational
inactive: Entity is inactive
blocked: Entity is blocked (requires reason)
suspended: Entity is suspended (requires reason)
rejected: Entity was rejected during onboarding (requires reason)

Note: Changing to blocked, suspended, or rejected requires providing a reason for audit purposes.

reason

string

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

riskMatrixId

string (uuid)

Risk matrix ID to assign to this entity. The risk matrix determines which rules will be executed for risk evaluation.

entityData

object

Entity-specific data structure. For person entities, use entityData.person. For company entities, use entityData.company.Person fields:

firstName: First name
lastName: Last name
middleName: Middle name
dateOfBirth: Date of birth (YYYY-MM-DD)
nationality: Nationality (ISO 3166-1 alpha-2)
email: Email address
phone: Phone number
address: Address object (street, city, state, country, postalCode)

Company fields:

legalName: Legal company name
tradingNames: Array of trading names
registrationNumber: Company registration number
incorporationDate: Date of incorporation (YYYY-MM-DD)
industry: Industry/sector
employees: Number of employees
website: Company website
address: Address object

attributes

object

Custom key-value attributes for flexible entity data storage

metadata

object

System metadata (usually set by the system, but can be updated)

Immutable Fields

The following fields cannot be changed after entity creation:

type: Entity type (person, company, transaction)
countryCode: Entity country code (ISO 3166-1 alpha-2)

Response

Returns the updated entity object.

entity

object

The updated entity object with all current values

evaluation

object | null

Evaluation object (currently null - re-evaluation feature temporarily disabled)

previousEntity

object

The entity state before the update (for audit purposes)

Example Request

curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Michael Doe",
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-0123"
      }
    },
    "riskMatrixId": "matrix-uuid-here"
  }'

Example Response

{
  "entity": {
    "id": "entity-uuid",
    "organizationId": "org-uuid",
    "externalId": "customer-12345",
    "type": "person",
    "name": "John Michael Doe",
    "taxId": "123-45-6789",
    "countryCode": "US",
    "status": "active",
    "riskScore": "35.00",
    "riskMatrixId": "matrix-uuid-here",
    "entityData": {
      "person": {
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-0123"
      }
    },
    "createdAt": "2025-12-20T10:00:00Z",
    "updatedAt": "2025-12-24T15:30:00Z"
  },
  "evaluation": null,
  "previousEntity": {
    "id": "entity-uuid",
    "name": "John Doe",
    "status": "pending",
    ...
  }
}

Status Change with Reason

When changing status to blocked, suspended, or rejected, you must provide a reason:

curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked",
    "reason": "Failed sanctions screening - OFAC match detected"
  }'

Use Cases

1. Update Customer Information

Update customer data from your CRM or user management system:

{
  "name": "Jane Smith-Johnson",
  "entityData": {
    "person": {
      "lastName": "Smith-Johnson",
      "email": "jane.smithjohnson@example.com",
      "address": {
        "street": "456 New St",
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postalCode": "98101"
      }
    }
  }
}

2. Assign Risk Matrix

Assign or change the risk matrix for an entity:

{
  "riskMatrixId": "high-risk-matrix-uuid"
}

After updating the risk matrix, you should trigger a re-analysis using POST /entities/:entityId/analyze to re-evaluate the entity with the new rules.

3. Block Entity After Investigation

Block an entity after compliance investigation:

{
  "status": "blocked",
  "reason": "Investigation revealed connections to sanctioned entities"
}

4. Sync Company Data

Update company information from business registry:

{
  "entityData": {
    "company": {
      "employees": 250,
      "revenue": 50000000,
      "website": "https://company-new-domain.com"
    }
  }
}

Events and Webhooks

Real-time Events

After a successful update, the following real-time event is emitted via WebSocket:

{
  "event": "entity.updated",
  "entityId": "entity-uuid",
  "externalId": "customer-12345",
  "updatedFields": ["name", "entityData"],
  "previousValues": {...},
  "newValues": {...}
}

Webhook Triggers

If you change only the status field (without other field changes), a webhook is triggered: Event: entity.status_changed

{
  "event": "entity.status_changed",
  "entityId": "entity-uuid",
  "externalId": "customer-12345",
  "oldStatus": "active",
  "newStatus": "blocked",
  "reason": "Failed sanctions screening",
  "changedBy": "user-uuid",
  "timestamp": "2025-12-24T15:30:00Z"
}

Note: If you update status along with other fields, the webhook is NOT triggered (assumes bulk entity edit rather than standalone status change).

Audit Trail

Every entity update creates an ATTRIBUTE_CHANGED event in the entity events log with:

Before state (all changed fields)
After state (all changed fields)
User who made the change
Timestamp
Source (API, dashboard, etc.)

Query audit trail:

GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED

Error Responses

404 Not Found

error

Entity with the specified externalId not found in your organization

{
  "error": "Entity not found"
}

400 Bad Request

error

Invalid request data or validation error

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

400 Bad Request

error

Attempting to change immutable fields

{
  "error": "Field 'type' cannot be changed after entity creation"
}

Best Practices

Always Set External ID on Creation: Set externalId when creating entities via POST /entities to enable updates by external ID.
Use for System Integration: This endpoint is ideal for integrations where you sync data from external systems (CRM, ERP, etc.) using your own IDs.
Provide Reasons for Status Changes: Always include meaningful reasons when blocking, suspending, or rejecting entities for compliance audit trail.
Re-analyze After Risk Matrix Change: After assigning a new risk matrix, trigger POST /entities/:entityId/analyze to re-evaluate with new rules.
Handle 404 Gracefully: If entity not found by external ID, you may need to create it first using POST /entities.
Batch Updates: For updating multiple entities, call this endpoint concurrently with different external IDs for better performance.

Create Entity - Create new entity
Update Entity by UUID - Update using internal UUID
Get Entity - Retrieve entity details
Analyze Entity - Trigger risk analysis

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

Update Entity by External ID

Overview

Path Parameters

Request Body

Immutable Fields

Response

Example Request

Example Response

Status Change with Reason

Use Cases

1. Update Customer Information

2. Assign Risk Matrix

3. Block Entity After Investigation

4. Sync Company Data

Events and Webhooks

Real-time Events

Webhook Triggers

Audit Trail

Error Responses

Best Practices

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Path Parameters

​Request Body

​Immutable Fields

​Response

​Example Request

​Example Response

​Status Change with Reason

​Use Cases

​1. Update Customer Information

​2. Assign Risk Matrix

​3. Block Entity After Investigation

​4. Sync Company Data

​Events and Webhooks

​Real-time Events

​Webhook Triggers

​Audit Trail

​Error Responses

​Best Practices

​Related Endpoints

Overview

Path Parameters

Request Body

Immutable Fields

Response

Example Request

Example Response

Status Change with Reason

Use Cases

1. Update Customer Information

2. Assign Risk Matrix

3. Block Entity After Investigation

4. Sync Company Data

Events and Webhooks

Real-time Events

Webhook Triggers

Audit Trail

Error Responses

Best Practices

Related Endpoints