Proxy Create Process

This document describes the overall process for creating new proxies on the platform, from initial data submission, through validation and review stages, to the final creation of the proxy record or handling of exceptions.

Overview

The Proxy Creation Process ensures the integrity and compliance of proxy data by performing comprehensive validation and review procedures. This process protects against inappropriate proxy assignments, maintains data quality standards, and ensures regulatory compliance across all platform operations. Proxies are individuals who have been granted specific rights to act on behalf of customers (natural persons, legal entities, or joint persons). Note: AML/KYC compliance verification occurs separately during the proxy onboarding process, not during the creation process itself.

Prerequisites

Partners need to:

  • Have an existing natural person who will act as the proxy

  • Have an existing entity (natural person, legal entity, or joint person) for whom the proxy will act

  • Gather all required proxy information including proxy type, scope type (for signatories), custody type (for guardians), and validity type

  • Ensure proper authorization to create the proxy

Validation Types

The proxy creation 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, including:

  • Field requirements validation - Ensures all required fields are provided (e.g., naturalPersonId, entityId, proxyType, validityType)

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

  • Format validation - Validates field formats using regex patterns where applicable

  • Data type validation - Ensures correct data types for all 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 validation - Ensures proxy type is valid and compatible with entity type

  • Entity Type compatibility - Validates that:

    • SIGNATORY proxies can only be created for LEGAL_ENTITY types

    • GUARDIAN proxies can only be created for NATURAL_PERSON types

  • Scope Type validation - For SIGNATORY proxies:

    • Field MUST be provided (cannot be empty)

    • Must be one of two values: INDIVIDUAL or JOINT

    • Cannot be provided for non-SIGNATORY proxy types

  • Custody Type validation - For GUARDIAN proxies:

    • Field MUST be provided (cannot be empty)

    • Must be one of two values: SINGLE_CUSTODY or JOINT_CUSTODY

    • Cannot be provided for non-GUARDIAN proxy types

  • Validity Type validation - Validates that validityType is compatible with proxy type:

    • GUARDIAN: only UNTIL_LEGAL_AGE

    • SIGNATORY: only UNLIMITED

    • GENERAL_POWER_OF_ATTORNEY: UNLIMITED, IN_CASE_OF_DEATH, UNTIL_CASE_OF_DEATH

    • INFORMATION_PROXY: UNLIMITED, UNTIL_CASE_OF_DEATH

    • LIQUIDATOR: only UNLIMITED

    • JOINT_ACCOUNT_HOLDER: only UNLIMITED

  • Entity relationship validation - Ensures naturalPersonId and entityId are different (proxy cannot be proxy for themselves)

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, status checks, and relationship validations specific to proxy creation.

Asynchronous validations include:

  • Natural person status validation (proxy natural person must be ACTIVE or CREATED)

  • Related entity status validation (must be ACTIVE or CREATED)

  • Proxy type-specific business logic validation

  • Guardian-specific validations (custody type, adult status, guardian count limits)

  • Signatory-specific validations (scope type matching with legal representatives)

  • Customer product existence validation

Business Process Flow

The creation process follows a structured workflow:

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

  2. Command Event Publishing - Proxy create command event is published

  3. Data Storage - Proxy data is stored with RECEIVED status

  4. Asynchronous Business Validation & Review - Comprehensive verification and routing decisions

  5. Proxy Creation - Official creation in the system

  6. Exception Handling - Management of rejected or problematic cases

How to Call the Create Endpoint

The create request is performed by calling the endpoint:

POST /roles/proxies

Validation Framework

Data Quality Assurance

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

Initial Data Verification

  • Ensures all required proxy information is provided

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

  • Confirms proper partner authorization

  • Validates natural person and related entity exist and are accessible

Business Validation Steps (Asynchronous)

  1. Natural Person Status Validation

    • Retrieves the proxy natural person

    • Verifies natural person status is ACTIVE or CREATED

    • Returns validation error if natural person has inappropriate status

  2. Related Entity Status Validation

    • Retrieves the related entity (natural person, legal entity, or joint person)

    • Verifies entity status is ACTIVE or CREATED

    • Returns validation error if entity has inappropriate status

  3. Proxy Type-Specific Validation

    • For GUARDIAN proxies:

      • Validates that related entity is a natural person

      • Checks if proxy natural person is adult (guardians must be adults)

      • Validates custody type consistency with existing guardians:

        • If SINGLE_CUSTODY guardian already exists, no additional guardians allowed

        • If JOINT_CUSTODY guardian already exists, cannot add SINGLE_CUSTODY guardian

      • Ensures guardian count limits are not exceeded (max 2 guardians total)

      • Validates custody type business rules:

        • SINGLE_CUSTODY: only one guardian allowed per natural person

        • JOINT_CUSTODY: requires exactly 2 guardians per natural person

    • For SIGNATORY proxies:

      • Validates that related entity is a legal entity

      • Validates that scope type is specified and provided

      • Retrieves legal representatives of the legal entity and validates that a legal representative is available for the signatory natural person

      • 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 signatory natural person is an active legal representative of the entity

    • For other proxy types (GENERAL_POWER_OF_ATTORNEY, INFORMATION_PROXY, LIQUIDATOR, JOINT_ACCOUNT_HOLDER):

      • Validates that related entity exists and has appropriate status

      • Validates validity type compatibility

      • No additional type-specific business logic validations

  4. Customer Product Validation

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

    • Returns validation error if any customer product is not found

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

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

    • Missing required fields (naturalPersonId, entityId, proxyType, validityType)

    • Invalid proxy type and entity type combinations (e.g., SIGNATORY for NATURAL_PERSON)

    • Missing scope type for SIGNATORY proxies

    • Missing custody type for GUARDIAN proxies

    • Invalid validity type for given proxy type

    • Same naturalPersonId and entityId (proxy cannot be proxy for themselves)

Business Impact:

  • Proxy creation is immediately rejected

  • Partner receives validation error notification

  • Partner must correct the submitted data and resubmit

Next Steps:

  • Review and correct the submitted data

  • Ensure all required fields are complete and properly formatted

  • Verify proxy type is compatible with entity type

  • Ensure scope type is provided for SIGNATORY proxies

  • Ensure custody type is provided for GUARDIAN proxies

  • Resubmit the corrected proxy data

2. Asynchronous Validation Failure

When it occurs:

  • Natural person has inappropriate status (not ACTIVE or CREATED)

  • Related entity has inappropriate status (not ACTIVE or CREATED)

  • Guardian-specific validation failures:

    • Guardian is not an adult (guardians must be 18+ years old)

    • Guardian count limit exceeded (maximum 2 guardians per natural person)

    • Custody type conflicts with existing guardians:

      • Trying to add SINGLE_CUSTODY when JOINT_CUSTODY guardian exists

      • Trying to add second guardian when SINGLE_CUSTODY guardian exists

      • Trying to add JOINT_CUSTODY when SINGLE_CUSTODY guardian exists

  • Signatory-specific validation failures:

    • 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

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

  • Customer product validation failures:

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

Business Impact:

  • Proxy creation is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • No proxy record is created in the system

Next Steps:

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

  • Ensure natural person and related entity have appropriate statuses

  • For guardian proxies: verify guardian is adult and custody type is appropriate

  • For signatory proxies: ensure natural person is legal representative with matching signature authorization

  • Verify all customer product IDs are valid

  • Resubmit proxy creation request after resolving validation issues

3. Successful Creation

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • Natural person and related entity have appropriate statuses

  • Proxy type-specific validations pass

  • Customer products are valid (if provided)

Business Impact:

  • Proxy is successfully created in system

  • Proxy status is set to CREATED

  • Partner receives success notification via webhook/notification

Business Rules

Entity Requirements

  • Proxies link natural persons with entities (natural person, legal entity, or joint person)

  • Natural person (proxy) must have status ACTIVE or CREATED

  • Related entity must have status ACTIVE or CREATED

  • Natural person and related entity must be different

Proxy Type Rules

GUARDIAN

  • Entity compatibility: Can only be created for NATURAL_PERSON entities

  • Custody type: Required - SINGLE_CUSTODY or JOINT_CUSTODY

  • Guardian requirements: Guardian must be an adult

  • Guardian limits: Maximum 2 guardians per natural person

  • Custody rules:

    • If SINGLE_CUSTODY guardian exists, no additional guardians allowed

    • If JOINT_CUSTODY guardian exists, SINGLE_CUSTODY guardian cannot be added

    • JOINT_CUSTODY requires exactly 2 guardians

  • Validity type: Must be UNTIL_LEGAL_AGE

  • Customer products: Can be assigned customer products

SIGNATORY

  • Entity compatibility: Can only be created for LEGAL_ENTITY entities

  • Scope type: Required - INDIVIDUAL or JOINT

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

  • Scope type rules:

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

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

  • Validity type: Must be UNLIMITED

  • Customer products: Can be assigned customer products

GENERAL_POWER_OF_ATTORNEY

  • Validity types: UNLIMITED, IN_CASE_OF_DEATH, UNTIL_CASE_OF_DEATH

  • Customer products: Can be assigned customer products

INFORMATION_PROXY

  • Validity types: UNLIMITED, UNTIL_CASE_OF_DEATH

  • Customer products: Can be assigned customer products

LIQUIDATOR

  • Validity type: Must be UNLIMITED

  • Customer products: Can be assigned customer products

JOINT_ACCOUNT_HOLDER

  • Validity type: Must be UNLIMITED

  • Customer products: Can be assigned customer products

Customer Product Rules

  • Customer product IDs must reference existing customer products in the system

  • Customer products can be assigned to any proxy type during creation

Status Rules

  • New proxies are created with RECEIVED status initially

  • After successful validation, status changes to CREATED

Last updated