Natural Person Create Process

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 individuals with similar core personal identifiers. "Basic data" in this context refers to fundamental
      personal details such as first name, last name, date of birth. This wider search helps flag cases where a person
      might already exist in the system with slightly different or incomplete information (e.g., a slightly different
      spelling).
  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 identifies existing global
    records with highly similar core identifying attributes, 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.

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