Natural Person Create - Rules and Outcomes

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

Overview

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

Prerequisites

Partners need to gather all required personal information before initiating the Natural Person creation process.

Validation Types

The natural person 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., firstName, lastName, email, phone)
• Field length validation - Validates minimum and maximum character limits (e.g., firstName max 255 characters,
  phone 3-20 characters)
• 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, length limits, and regex patterns, refer to the OpenAPI schema definitions
&#xNAN;in reference/entities.yaml

Business Logic Validations:

• US Citizenship Relationship validation - Validates consistency between US nationality flags and nationality list
• US Nationality validation - Ensures proper US nationality declaration if person has US nationality
• Tax Details validation - Validates tax residency information format and requirements
• Address validation - Validates address format and structure (main address is required)
• NACE Sectors validation - Validates NACE sector codes against valid sectors list and checks section patterns
• Geographic compliance - Validates main address country against whitelisted residencies

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, duplicate detection, and compliance checks.

Asynchronous validations include:

• Global duplicate detection across the entire system
• Restricted data changes validation
• Matching with existing global records
• Geographic compliance checks - Validates main address country against whitelisted residencies
• NACE sector business validity (against valid/banned sector lists)

Business Process Flow

The creation process follows a structured workflow:

1. Immediate Static Validation - Format and structure verification (synchronous)
2. Data Storage - Natural person data is stored with initial status
3. Asynchronous Business Validation & Review - Comprehensive verification and routing decisions
4. Natural Person Creation - Official creation in the system or routing to review
5. Exception Handling - Management of rejected or problematic cases

How to Call the Create Endpoint

The create request is performed by calling the endpoint:

POST /entities/natural-persons

Validation Framework

Data Quality Assurance

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

Initial Data Verification

• Ensures all required natural person information is provided
• Validates data format and completeness using static validations (immediate)
• Confirms proper partner authorization

Business Validation Steps (Asynchronous)

1. NACE Sectors Validation
   • Gets valid NACE sectors for natural persons
   • Checks if each declared sector is on the valid list
   • Verifies sector is not banned (banned list is empty for natural persons)
   • Returns validation error if any sector is invalid
2. Natural Person Data Validation
   • Validates personal data using business rules
   • Checks required fields and data formats
   • Ensures data meets system requirements
3. Global Duplicate Detection

   • Searches for matching person basic data across the system's global database. This search uses core identifying
     attributes of a person.

   • Compares with existing records system-wide to identify potential exact matches (duplicates).

   • Finds potential duplicates regardless of the originating partner or system source.

   • Identifies similar persons by basic data: If an exact match isn't found, the system performs a broader search
     for persons that may be the same individual. An existing person (natural person, legal representative or
     beneficial owner, of any partner) is considered similar when all of the following hold:

     • the date of birth is the same, and
     • the birth country is the same, and
     • at least one of:
       • the first names share at least one word (e.g., Anna Maria and Maria),
       • the last name is the same,
       • the birth place is the same.

     Names and birth places are compared ignoring upper/lower case and leading/trailing spaces, but otherwise as
     written. A person whose first name, last name and birth place are all spelled differently is not considered
     similar. If at least one similar person is found, the creation goes to manual review (MATCHING_SIMILARITIES).

4. Restricted Data Changes Check
   • Compares critical personal information with existing global records if a potential match (based on basic data)
     is found in the system's global database.
   • Generates a summary of differences for review: If the new information for an apparently existing person shows
     changes in specific, pre-defined critical fields, these differences are highlighted for a manual compliance
     review.
   • Flags data conflicts requiring manual review.
   • Restricted (Critical) Data: The system maintains a list of personal data fields considered critical for
     identity and compliance. When a new natural person is being created and a corresponding global person record
     already exists, the system compares these critical fields. This includes core identity details (like name, date of
     birth) and other sensitive information (like tax identifiers or key contact details, e.g., tax details
     modifications). If the incoming data suggests a modification to these existing global details, it is flagged for
     review.

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

• Incomplete or incorrectly formatted natural person data. This includes checks for:
  • Validity and completeness of personal basic data (e.g., first name, last name, birthdate, birthplace, birth
    country, tax details).
  • Validity and completeness of contact data (e.g., address, email, phone number).
  • Presence of all other required fields.
  • Correct data formats for all fields.
• Invalid NACE sector codes (e.g., sector not on the valid list for natural persons).
• An attempt to create a natural person that already exists for the given partner.

Business Impact:

• Natural person creation is immediately rejected
• Partner receives validation error notification
• Partner must create a new natural person instead of correcting the existing one

Next Steps:

• Review and correct the submitted data
• Ensure all required fields are complete
• Verify NACE sectors are valid
• Resubmit the corrected natural person data

2. Manual Review Required (Asynchronous Decision)

When it occurs:

• Person basic data found in global database: An existing record matching core identifying attributes (like first
  name, last name, date of birth, birthplace and birth country or tax details) of the incoming natural person is found
  in the system's central database.
• Matching data diff patch generated: Changes are detected in critical personal or contact information when
  comparing the incoming data against an existing global record for that individual.
• Similar persons found by basic data: Even if no exact match is found, the system finds an existing person with
  the same date of birth and birth country and at least one of the same first name word, last name or birth place
  (see step 3, Global Duplicate Detection), suggesting a potential duplicate.
• Restricted data changes detected: The process identifies discrepancies in pre-defined critical data fields between
  the incoming natural person information and an existing global record for that individual.

Business Impact:

• Natural person status is set to "Under Review"
• admin is notified for manual verification
• Natural person creation is temporarily suspended
• Partner receives notification about review status via webhook/notification

Review Process:

• Admin task process is initiated
• Natural person status set to REVIEW
• Admin task data includes difference patch and similar persons
• Decision callback returns to the natural person create process

Admin Task Reasons:

• MATCHING_SIMILARITIES - Created when no exact match is found but similar records are discovered in the global
  database. This task type handles cases where potential duplicates exist based on similar core identifying attributes.
  • Available Admin Decisions:
    • MATCH - Admin confirms that the natural person should be matched with an existing global record. Admin
      must provide the global_id of the existing record to match with.
    • NOT_MATCH - Admin confirms that the natural person is unique and should be created as a new record without
      matching to any existing global record.
• NATURAL_PERSON_CREATE - Created when an exact match is found and changes are detected in critical data fields.
  This task type handles cases where restricted data modifications require manual review and approval.
  • Available Admin Decisions:
    • APPROVE - Admin approves the critical data changes. The global record will be updated with the new
      information and the natural person will be successfully created.
    • REJECT - Admin rejects the critical data changes. The natural person creation will be rejected and no
      changes will be made to the global record.

Using the natural person while the review is pending:

Until the admin decides, the natural person is not created yet. It can be read with
GET /entities/natural-persons/{naturalPersonId} (status REVIEW, no globalId), but it cannot be used in any other
request. Every request that references it is rejected synchronously with HTTP 400, errorCode VALIDATION and an
error detail with code VALIDATION_ENTITY_PENDING_REVIEW whose parameter is the natural person id. This applies,
for example, to:

• updating the natural person, its identification, identification verification, trading profile, investment
  objectives and appropriateness test responses
• uploading (resourceType NATURAL_PERSON) and signing documents
• creating a customer, a proxy (as proxy or as managed entity), a joint person or a tax exemption order

The REVIEW status is cleared only by Tradevest's internal review decision. The partner cannot clear or shorten the
review through the API: updating the natural person is rejected like every other request. Do not create the same
person again while the review is pending; the new request is not treated as a duplicate and starts a second review.

Wait for the natural person status webhook. Once the review is decided, the natural person is either created
(MATCH, NOT_MATCH, APPROVE) or becomes INVALID (REJECT). After creation, the same naturalPersonId can be
used for all operations. A natural person that enters REVIEW later, through an update or a KYC result, already
exists and is not affected by this rule.

3. Automatic Approval (Direct Creation)

When it occurs:

• All validations pass (both immediate and asynchronous)
• No matching data diff patch generated
• No similar persons found
• Natural person data is valid

Business Impact:

• Natural person will be successfully created in system
• Natural person status will be set to CREATED
• Partner receives success notification via webhook/notification

Business Rules

Partner-Specific Duplicate Prevention

• All natural person data is validated in the context of the specific partner
• The system prevents creation of duplicate natural persons within the same partner
• If an attempt is made to create a natural person that already exists for the given partner, the request is immediately
  rejected
• Partner receives notification about the duplicate rejection via webhook

NACE Sectors

• Only valid NACE sectors for natural persons are accepted
• Invalid sectors return validation error
• Banned sectors list is empty for natural persons

Geographic Rules

• Certain countries trigger review
• Whitelisted residencies allow direct processing
• Non-whitelisted locations may require review