Natural Person Update Process

This document describes the comprehensive process for updating existing natural persons on the platform, from initial data submission and validation, through review stages, to the final data update or handling of exceptions.

Overview

The Natural Person Update Process ensures the integrity and compliance of natural person data changes by performing comprehensive validation and review procedures. This process protects against unauthorized changes, maintains data quality standards, and ensures regulatory compliance across all platform operations.

Prerequisites

Partners need to:

  • Have created a Natural Person with CREATED or ACTIVE status

  • Upload necessary supporting documents before initiating updates for certain fields (only for natural person in ACTIVE status)

  • Provide appropriate document references (documentId) for specific types of updates (only for natural person in ACTIVE status)

Required Documents

For specific types of Natural Person data updates, providing an appropriate supporting document is mandatory for entity in status ACTIVE:

Document Requirements by Field:

  • firstName - KYC document, document type: KYC

  • lastName - document confirming name change, document type: KYC

  • gender - KYC document, document type: KYC

  • title - document confirming obtaining the title, document type: KYC

  • mainAddress outside Germany - proof of residence document, document type: PROOF_OF_RESIDENCE

  • deathDay - death certificate, document type: DEATH_CERTIFICATE

The document identifier (documentId) must be provided in the update request for the above-mentioned fields for natural person in status ACTIVE.

Validation Types

The natural person 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.

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

  • Field length validation - Validates minimum and maximum character limits

  • Format validation - Validates field formats using regex patterns (e.g., email format, phone number patterns)

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

For detailed field specifications, refer to the OpenAPI schema definitions in reference/entities.yaml

Business Logic Static Validations:

  • Document ID requirement validation - Validates that documentId is provided for fields that require it ( firstName, lastName, gender, title, deathDay) and natural person in status ACTIVE

  • Death day exclusive update validation - If deathDay is being updated, ensures no other fields are being updated simultaneously, and it only can be updated for natural person in status ACTIVE

  • Contact validation - Validates contact information format and structure if provided

  • NACE Sectors validation - Validates NACE sector codes format if provided

  • Basic status validation - Ensures natural person exists and has CREATED or ACTIVE status

2. Asynchronous Business Validations

These validations are performed asynchronously after the endpoint returns a successful response. Results are delivered via webhooks or notification systems.

Asynchronous validations include:

  • Document existence and type validation - Verifies provided documentId references existing document of correct type

  • Natural person status validation - Validates person status allows the specific type of update

  • Geographic compliance checks - Validates address changes against whitelisted residencies

  • NACE sector business validity - Validates NACE sectors against valid/banned sector lists and normalizes them

  • Restricted data changes detection - Identifies changes in critical fields requiring manual review

  • Tax details restrictions validation - Validates tax-related information changes

Update Process Types

There are 2 different flows for updating a Natural Person:

1. Death Day Update Process

Special process for updating only the death day field.

2. Standard Data Update Process

Process for updating all other natural person data fields.

How to Call the Update Endpoint

The update is performed by calling the endpoint:

PATCH /entities/natural-persons/{naturalPersonId}

The request structure should contain a NaturalPersonUpdate object:

{
  "naturalPersonUpdateData": {
    // data to be updated
  },
  "documentId": "uuid-of-supporting-document"
  // required for specific fields
}

Validation Framework

Data Quality Assurance

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

Initial Static Verification (Synchronous)

  • Ensures all required update information is provided and properly formatted

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

  • Confirms proper partner authorization and natural person existence

  • Validates document ID requirements for specific fields

Business Validation Steps (Asynchronous)

  1. Natural Person Status Validation

    • Validates that natural person has CREATED or ACTIVE status

    • Only natural persons with CREATED or ACTIVE status can be updated

    • Returns validation error if natural person does not have CREATED or ACTIVE status

  2. Document Validation

    • Retrieves all documents associated with the natural person in status ACTIVE

    • Validates that provided documentId exists and references correct document type

    • Ensures document type matches requirements for specific field updates

    • Returns validation error if document doesn't exist or has wrong type

  3. NACE Sectors Validation

    • Gets valid NACE sectors for natural persons

    • Validates and normalizes provided NACE sector codes

    • Checks if each declared sector is on the valid list

    • Returns validation error if any sector is invalid

  4. Geographic Compliance Validation

    • Validates address changes against whitelisted residencies

    • Checks if main address country changes trigger review requirements

    • Validates proof of residence document requirements for non-German addresses

  5. Restricted Data Changes Detection Natural Person in status CREATED:

    • Validates data completeness and consistency for initial data setup

    • Performs global matching validation - checks if global data is already used in the system

    • Generates a summary of differences for review: If changes in pre-defined critical fields are detected, these differences are highlighted for manual compliance review

    • Flags data conflicts requiring manual review if matching entities are found and natural person data is being updated

    • No document requirements - updates can proceed without supporting documentation

    • Critical Data Fields - The system maintains a list of personal data fields considered critical for identity and compliance, including core identity details (name, gender, title), tax information, and certain address changes Natural Person in status ACTIVE:

    • Compares critical personal information with existing data to detect significant changes

    • Generates a summary of differences for review: If changes in pre-defined critical fields are detected, these differences are highlighted for manual compliance review

    • Flags data conflicts requiring manual review based on change significance and regulatory requirements

    • Critical Data Fields: The system maintains a list of personal data fields considered critical for identity and compliance, including core identity details (name, gender, title), tax information, and certain address changes

  6. KYC Screening & Verification

    • External provider data validation - Updated personal data is sent to external KYC/AML screening services for verification

    • Data authenticity verification - Validates the accuracy and legitimacy of personal information against compliance databases

    • Compliance screening - Checks updated data against regulatory watchlist and sanctions databases

    • Risk assessment - Evaluates potential compliance risks associated with the data changes

    • Verification outcomes: Valid (automatic approval), Manual Review Required, Repeat KYC, or Rejected

  7. Death Day Specific Validations

    • Validates death day is after birth day

    • Ensures death day update is exclusive (no other fields updated simultaneously)

    • Checks for entities where this natural person is the only active proxy

    • Creates admin tasks for entities that would lose their only proxy

Business Process Flow

The update process follows a structured workflow:

  1. Immediate Static Validation - Format, structure, and basic business rule verification (synchronous)

  2. Natural Person Retrieval - Fetch existing natural person data and validate update eligibility

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

  4. KYC Screening & Verification - External provider validation of data authenticity and compliance (Natural Person in status ACTIVE only)

  5. Natural Person Update - Official update in the system or routing to review

  6. Exception Handling - Management of rejected or problematic cases

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

  • Incomplete or incorrectly formatted natural person update data

  • Missing required documentId for fields that require documentation

  • Attempt to update death day along with other fields

  • Natural person not found or does not have CREATED or ACTIVE status

  • Invalid NACE sector codes

  • Document doesn't exist or has wrong type

Business Impact:

  • Natural person 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

  • Ensure all required document IDs are provided

  • Verify NACE sectors are valid

  • Resubmit the corrected natural person update

2. Manual Review Required (Asynchronous Decision)

When it occurs:

  • Global matching conflicts detected (Natural Person in status CREATED): System identifies that critical personal data being updated already exists for other entities in the system, requiring manual verification

  • Restricted data changes detected (Natural Person in status ACTIVE): Changes are identified in pre-defined critical data fields (firstName, lastName, gender, title, tax details, non-whitelisted address changes)

  • Geographic compliance concerns: Main address changes to non-whitelisted countries

  • Tax details modifications: Changes in tax-related information that require compliance review

Business Impact:

  • Natural person update status is set to "Under Review"

  • Admin is notified for manual verification

  • Natural person update is temporarily suspended

  • Partner receives notification about review status via webhook/notification

Review Process:

  • Admin task process is initiated for manual review

  • Admin reviews the proposed changes and their impact

  • Admin can approve or reject the update

  • Decision callback returns to the natural person update process

3. Automatic Approval (Direct Update)

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • No global matching conflicts detected (Natural Person in status CREATED): No other entities in the system use the critical personal data being updated, allowing direct update without manual review

  • No restricted data changes detected (Natural Person in status ACTIVE): Changes do not involve pre-defined critical data fields requiring manual review

  • Natural person has CREATED or ACTIVE status

  • All required documents for natural person in status ACTIVE are provided and valid

  • Geographic and compliance requirements are met

Business Impact:

  • Natural person data is successfully updated in the system

  • Partner receives success notification via webhook/notification

  • Updated data is immediately available for use

4. Death Day Update Special Process

When it occurs:

  • Only death day field is being updated

  • Valid death certificate document is provided

Special Process:

  • System checks for entities where this natural person is the only active proxy

  • Admin tasks are created for each affected entity to assign new proxies

  • Natural person's death day is updated

  • Related statuses (proxy role, customer role, entity statuses) are updated accordingly

  • Process completes after creating admin tasks for affected entities without active proxies

5. KYC Screening Failure (Natural Person in status ACTIVE)

When it occurs:

  • KYC screening identifies compliance issues with updated personal data

  • External provider flags data as suspicious or requiring additional verification

  • Updated information conflicts with regulatory databases or watchlist

  • Data authenticity cannot be verified by external screening services

Business Impact:

  • Natural person update is rejected or routed to manual review based on severity

  • Admin task is created for compliance team verification

  • Natural person may be flagged for enhanced monitoring or rejected globally

Review Process:

  • Compliance admin reviews KYC screening results and data conflicts

  • Admin can approve with additional monitoring, request more documentation, or reject globally

  • Decision callback returns to the natural person update process

Business Rules

Status-Based Update Rules

  • CREATED or ACTIVE status: Only natural persons with CREATED or ACTIVE status can be updated

  • All other statuses: Updates are not allowed regardless of status

Document Requirements

  • Document ID must be provided for natural person in status ACTIVE and fields firstName, lastName, gender, title, deathDay updates

  • Document type must match field requirements (KYC, PROOF_OF_RESIDENCE, OTHER)

  • Documents must exist and be associated with the natural person

NACE Sectors

  • Only valid NACE sectors for natural persons are accepted

  • Invalid sectors return validation error

  • Sectors are automatically normalized during validation

Geographic Rules

  • Main address changes to non-German countries require PROOF_OF_RESIDENCE document

  • Non-whitelisted residency countries trigger manual review

  • US addresses (non-main) trigger review requirements

Death Day Rules

  • Death day must be after birth day

  • Death day updates cannot be combined with other field updates

  • Death certificate document (type: OTHER) is required

  • System handles proxy reassignment for affected entities

Tax Details Rules

  • Certain tax detail changes are considered restricted and trigger review

  • Tax-related updates require compliance verification

Specific conditions that trigger manual review:

  1. German Tax ID Changes:

    • When updating a tax detail with taxResidency = "DE" (Germany)

    • AND the new taxId is different from all existing German Tax IDs

    • Example: Person has German Tax ID "12345" and tries to change it to "67890"

  2. US Tax Residency Addition:

    • When adding ANY tax detail with taxResidency = "US" (United States)

    • This always triggers review regardless of Tax ID value

    • Example: Adding any US tax residency information automatically requires manual verification

Last updated