Proxy Update Process

This document describes the overall process for updating existing proxies on the platform, from initial data submission, through validation stages, to the final update of the proxy record or handling of exceptions.

Overview

The Proxy Update Process ensures the integrity and compliance of proxy data modifications by performing comprehensive validation procedures. This process maintains data quality standards, ensures regulatory compliance, and handles proxy relationship updates efficiently across all platform operations. Note: AML/KYC compliance verification occurs separately during the proxy onboarding process, not during the update process itself.

Prerequisites

Partners need to:

  • Have an existing proxy with appropriate status for updates (CREATED or ACTIVE)

  • Gather all required update information

  • Ensure proper authorization to update the proxy data

  • Provide required documents for certain types of updates (scope type, custody type changes)

Validation Types

The proxy update process includes two types of validations:

1. Immediate Static Validations (Synchronous)

These validations are performed immediately when calling the endpoint and return errors directly to the user without delay. They validate data format, structure, and basic business rules to ensure data quality and completeness.

Static validations include:

API Layer Validations (OpenAPI Schema):

All field-level validations defined in the OpenAPI schema are automatically enforced for ProxyUpdate, including:

  • Field length validation - Validates minimum and maximum character limits for updated fields

  • Format validation - Validates field formats using regex patterns for updated fields

  • Data type validation - Ensures correct data types for all updated fields

  • Enum validation - Validates that enum fields contain only allowed values

For detailed field specifications, length limits, and regex patterns, refer to the OpenAPI schema definitions in reference/roles.yaml

Business Logic Validations:

  • Proxy Type Update validation - Validates proxy type compatibility with entity type when updating proxy type:

    • SIGNATORY can only be updated for LEGAL_ENTITY types

    • GUARDIAN can only be updated for NATURAL_PERSON types

    • Proxy type can ONLY be updated when proxy status is CREATED

  • Scope Type Update validation - For SIGNATORY proxies:

    • Must be one of two values: INDIVIDUAL or JOINT

    • Requires documentId pointing to CURRENT_REGISTRY_EXTRACT document for LEGAL_ENTITY

    • Cannot be updated for non-SIGNATORY proxy types

  • Custody Type Update validation - For GUARDIAN proxies:

    • Must be one of two values: SINGLE_CUSTODY or JOINT_CUSTODY

    • Requires documentId pointing to PROOF_OF_SINGLE_CUSTODY document for PROXY

    • Cannot be updated for non-GUARDIAN proxy types

  • Validity Type Update validation - Validates that updated validity type is compatible with proxy type:

    • Can only be updated for GENERAL_POWER_OF_ATTORNEY and INFORMATION_PROXY types

    • Must match allowed validity types for the proxy type

  • Customer Product Update validation - Validates that customer products can only be updated for GENERAL_POWER_OF_ATTORNEY and INFORMATION_PROXY proxy types (other types cannot have customer products updated)

  • Document ID validation - Ensures documentId is provided when updating scopeType or custodyType

2. Asynchronous Business Validations

These validations are performed asynchronously after the endpoint returns a successful response. Results are delivered via webhooks or notification systems. They include complex business logic and compliance checks specific to proxy updates.

Asynchronous validations include:

  • Existing proxy retrieval and status verification

  • Proxy type-specific update validations

  • Document type and resource type validation for required documents

  • Scope type matching with legal representatives (for signatory updates)

  • Custody type consistency with existing guardians (for guardian updates)

  • Customer product existence validation

Business Process Flow

The update process follows a structured workflow:

  1. Proxy Retrieval - Existing proxy is fetched and verified

  2. Immediate Static Validation - Format and structure verification (synchronous)

  3. Command Event Publishing - Proxy update command event is published

  4. Asynchronous Business Validation - Comprehensive verification and routing decisions

  5. Proxy Update - Official update in the system

  6. Exception Handling - Management of rejected or problematic cases

How to Call the Update Endpoint

The update request is performed by calling the endpoint:

PUT /roles/proxies/{proxyId}

Validation Framework

Data Quality Assurance

The validation process performs thorough checks to ensure data accuracy and completeness:

Initial Data Verification

  • Verifies proxy exists and is accessible

  • Validates update data format and completeness using static validations (immediate)

  • Confirms proper partner authorization

  • Validates proxy status allows updates

Business Validation Steps (Asynchronous)

  1. Proxy Existence and Status Validation

    • Retrieves the existing proxy by UUID

    • Verifies proxy exists and belongs to the correct partner

    • Verifies proxy status allows updates (CREATED or ACTIVE)

    • Returns validation error if proxy is not found, not accessible, or has inappropriate status

  2. Proxy Type Update Validation (when proxyType is provided)

    • Validates proxy can only change type when status is CREATED

    • Validates new proxy type compatibility with entity type

    • Performs proxy type-specific validations with updated values

  3. Document Validation (when documentId is provided)

    • For Scope Type Updates:

      • Validates document is CURRENT_REGISTRY_EXTRACT for LEGAL_ENTITY

      • Ensures document is associated with the correct legal entity

    • For Custody Type Updates:

      • Validates document is PROOF_OF_SINGLE_CUSTODY for PROXY

      • Ensures document is associated with the correct proxy

  4. Scope Type Update Validation (for SIGNATORY proxies)

    • Retrieves legal representative of the legal entity using proxy's natural person global ID and validates that a legal representative is available for scope type updates

    • Validates scope type matches legal representative's signature authorization:

      • INDIVIDUAL scope: requires legal representative with sole signature authorization (SoleSignatureAuthorized = true)

      • JOINT scope: requires legal representative without sole signature authorization (SoleSignatureAuthorized = false)

    • Ensures legal representative is active

  5. Custody Type Update Validation (for GUARDIAN proxies)

    • Validates custody type consistency with other existing guardians:

      • Cannot change to SINGLE_CUSTODY if JOINT_CUSTODY guardian exists

      • Cannot change to JOINT_CUSTODY if SINGLE_CUSTODY guardian exists

    • Ensures custody type business rules are maintained:

      • SINGLE_CUSTODY: only one guardian allowed per natural person

      • JOINT_CUSTODY: requires exactly 2 guardians per natural person

  6. Customer Product Validation

    • Validates that all provided customer product IDs exist in the system

    • Ensures customer products can only be updated for allowed proxy types

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

  • Incomplete or incorrectly formatted proxy update data. This includes checks for:

    • Invalid proxy type for entity type (when updating proxy type)

    • Missing documentId for scope type or custody type updates

    • Invalid validity type for proxy type

    • Invalid customer products for proxy type

    • Attempting to update proxy type when status is not CREATED

Business Impact:

  • Proxy update is immediately rejected

  • Partner receives validation error notification

  • Partner must correct the submitted data and resubmit

Next Steps:

  • Review and correct the submitted update data

  • Verify proxy type is compatible with entity type

  • Ensure documentId is provided for scope type and custody type updates

  • Verify validity type is compatible with proxy type

  • Resubmit the corrected proxy update data

2. Asynchronous Validation Failure

When it occurs:

  • Proxy not found or not accessible by partner

  • Proxy has inappropriate status for updates (not CREATED or ACTIVE)

  • Document validation failures:

    • Document is not of required type (CURRENT_REGISTRY_EXTRACT for scope updates, PROOF_OF_SINGLE_CUSTODY for custody updates)

    • Document is not for correct resource type (LEGAL_ENTITY for scope updates, PROXY for custody updates)

  • Scope type validation failures:

    • Natural person is not an active legal representative of the legal entity

    • Scope type doesn't match legal representative's signature authorization:

      • INDIVIDUAL scope provided but legal representative has SoleSignatureAuthorized = false

      • JOINT scope provided but legal representative has SoleSignatureAuthorized = true

  • Custody type validation failures:

    • Custody type conflicts with existing guardians:

      • Trying to change to SINGLE_CUSTODY when JOINT_CUSTODY guardian exists

      • Trying to change to JOINT_CUSTODY when SINGLE_CUSTODY guardian exists

    • Custody type business rules violations

  • Customer product validation failures:

    • One or more provided customer product IDs do not exist in the system

    • Customer products provided for proxy types that don't support updates (only GENERAL_POWER_OF_ATTORNEY and INFORMATION_PROXY can have customer products updated)

Business Impact:

  • Proxy update is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • Proxy remains in its original state

Next Steps:

  • Address the specific validation failure based on error details received in webhook

  • Ensure proxy has appropriate status for updates (CREATED or ACTIVE)

  • For scope type updates: ensure natural person is legal representative with matching signature authorization and provide correct document

  • For custody type updates: ensure custody type is compatible with existing guardians and provide correct document

  • Verify all customer product IDs are valid

  • Resubmit proxy update request after resolving validation issues

3. Successful Update

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • Documents are valid (if provided)

  • Scope type and custody type validations pass (if applicable)

  • Customer products are valid (if provided)

Business Impact:

  • Proxy is successfully updated in system

  • Partner receives success notification via webhook/notification

Business Rules

Update Eligibility

  • Proxies can only be updated if status is CREATED or ACTIVE

  • Proxy type can only be updated when status is CREATED

  • Partner must have proper authorization to update the proxy

Document Requirements

  • Scope Type Updates: Require documentId pointing to CURRENT_REGISTRY_EXTRACT document for LEGAL_ENTITY

  • Custody Type Updates: Require documentId pointing to PROOF_OF_SINGLE_CUSTODY document for PROXY

Proxy Type Update Rules

  • Type changes allowed only for CREATED status: Proxy type can only be updated when proxy status is CREATED

  • Entity compatibility: Updated proxy type must be compatible with entity type

  • Specific validations: Type-specific validations apply for updated proxy type

Scope Type Update Rules (SIGNATORY proxies)

  • Legal representative validation: Natural person must be an active legal representative of the legal entity

  • Signature authorization matching:

    • INDIVIDUAL scope: legal representative can sign alone (SoleSignatureAuthorized = true)

    • JOINT scope: legal representative requires joint signatures (SoleSignatureAuthorized = false)

  • Document requirement: CURRENT_REGISTRY_EXTRACT document for LEGAL_ENTITY must be provided via documentId

Custody Type Update Rules (GUARDIAN proxies)

  • Consistency with existing guardians: Updated custody type must not conflict with other guardians

  • Business rules enforcement:

    • Cannot change to SINGLE_CUSTODY if JOINT_CUSTODY guardian exists

    • Cannot change to JOINT_CUSTODY if SINGLE_CUSTODY guardian exists

  • Document requirement: PROOF_OF_SINGLE_CUSTODY document for PROXY must be provided via documentId

Validity Type Update Rules

  • Allowed proxy types: Validity type can only be updated for GENERAL_POWER_OF_ATTORNEY and INFORMATION_PROXY

  • Type compatibility: Updated validity type must be compatible with proxy type

Customer Product Update Rules

  • Update restrictions: Customer products can only be updated for GENERAL_POWER_OF_ATTORNEY and INFORMATION_PROXY proxy types

  • Other proxy types: GUARDIAN, SIGNATORY, LIQUIDATOR, and JOINT_ACCOUNT_HOLDER cannot have customer products updated

  • Existence validation: All customer product IDs must reference existing customer products

Field Update Restrictions

  • naturalPersonId: Cannot be updated

  • entityId: Cannot be updated

  • entityType: Cannot be updated

  • status: Cannot be updated directly through update endpoint

Last updated