NaturalPerson

Table

Description: NaturalPerson is the identity of an individual person. It contains the core, verifiable components of an individual's identity. which are verified against their passport, utility bills, government records etc. during Know Your Client (KYC) checks. Note on Required Fields: Fields marked as 'Required' are essential for a successful compliance check, but are not mandatory for creation.

note

The protobuf file is the authoritative source of documentation. Please refer to the Protobuf tab when in doubt about field definitions, validation rules, or type specifications.

Field	Type	Description	Required	Validation
full_name	string	The client's full legal name, as it appears on their official identification documents. Required for verification.	No	None
date_of_birth	Date	The client's date of birth. Required for verification.	Yes	None
country_of_citizenship	string	The ISO 3166-1 alpha-2 country code of the client's nationality/citizenship. This is the two-letter country code (e.g., "ZA" for South Africa, "NL" for the Netherlands). The value should be in uppercase. See https://www.iso.org/iso-3166-country-codes.html for a full list. Required for verification.	No	None
identification_number	string	An identification number for the client, as found on the provided document. The format is dependent on the identification_document_type. Required for verification.	No	None
identification_document_type	IdentificationDocumentType	The type of identification document provided to prove the correctness of the given identification_number (e.g., Passport, Driver's License). Required for verification.	No	None
identification_document_expiry_date	Date	The expiration date of the identification document, if applicable. Required for verification if the document has an expiry date.	Yes	None
physical_address	Address	The client's primary physical residential address. If postal_address is not provided, this address will also be used for postal mail. Required for verification.	Yes	None
postal_address	Address	The client's postal address, if it is different from the physical address. Optional for verification.	Yes	None
pep_status	PepStatus	The client's status as a Politically Exposed Person (PEP). This is a mandatory check for regulatory compliance. Required for verification.	No	None
contact_details	ContactDetails	The individual's personal contact details (personal email, personal mobile). Optional for verification.	Yes	None
sources_of_income	SourceOfIncomeAndWealth[]	The primary sources of the client's regular income (e.g., employment, pension). Required for verification.	No	None
sources_of_wealth	SourceOfIncomeAndWealth[]	The origins of the client's total net worth or assets (e.g., inheritance, investments). This is distinct from the source of income. Required for verification.	No	None
tax_residencies	TaxResidency[]	The client's tax residency information, required for CRS/FATCA reporting. A client can be a tax resident in multiple jurisdictions. Required for verification.	No	None

Protobuf

syntax = "proto3";

package meshtrade.compliance.client.v1;

import "google/type/date.proto";
import "meshtrade/compliance/client/v1/identification_document_type.proto";
import "meshtrade/compliance/client/v1/pep_status.proto";
import "meshtrade/compliance/client/v1/source_of_income_and_wealth.proto";
import "meshtrade/compliance/client/v1/tax_residency.proto";
import "meshtrade/type/v1/address.proto";
import "meshtrade/type/v1/contact_details.proto";

option go_package = "github.com/meshtrade/api/go/compliance/client/v1;clientv1";
option java_package = "co.meshtrade.api.compliance.client.v1";

/*
   NaturalPerson is the identity of an individual person.
   It contains the core, verifiable components of an individual's identity. which are
   verified against their passport, utility bills, government records etc. during Know Your Client (KYC) checks.
   Note on Required Fields: Fields marked as 'Required' are essential
   for a successful compliance check, but are not mandatory for creation.
*/
message NaturalPerson {
  /*
     The client's full legal name, as it appears on their official identification documents.
     Required for verification.
  */
  string full_name = 1;

  /*
     The client's date of birth.
     Required for verification.
  */
  google.type.Date date_of_birth = 2;

  /*
     The ISO 3166-1 alpha-2 country code of the client's nationality/citizenship.
     This is the two-letter country code (e.g., "ZA" for South Africa,
     "NL" for the Netherlands). The value should be in uppercase.
     See https://www.iso.org/iso-3166-country-codes.html for a full list.
     Required for verification.
  */
  string country_of_citizenship = 3;

  /*
     An identification number for the client, as found on the provided document.
     The format is dependent on the identification_document_type.
     Required for verification.
  */
  string identification_number = 4;

  /*
     The type of identification document provided to prove the correctness of the
     given identification_number (e.g., Passport, Driver's License).
     Required for verification.
  */
  meshtrade.compliance.client.v1.IdentificationDocumentType identification_document_type = 5;

  /*
     The expiration date of the identification document, if applicable.
     Required for verification if the document has an expiry date.
  */
  google.type.Date identification_document_expiry_date = 6;

  /*
     The client's primary physical residential address.
     If `postal_address` is not provided, this address will also be used for postal mail.
     Required for verification.
  */
  meshtrade.type.v1.Address physical_address = 7;

  /*
     The client's postal address, if it is different from the physical address.
     Optional for verification.
  */
  meshtrade.type.v1.Address postal_address = 8;

  /*
     The client's status as a Politically Exposed Person (PEP).
     This is a mandatory check for regulatory compliance.
     Required for verification.
  */
  meshtrade.compliance.client.v1.PepStatus pep_status = 9;

  /*
     The individual's personal contact details (personal email, personal mobile).
     Optional for verification.
  */
  meshtrade.type.v1.ContactDetails contact_details = 10;

  /*
     The primary sources of the client's regular income (e.g., employment, pension).
     Required for verification.
  */
  repeated meshtrade.compliance.client.v1.SourceOfIncomeAndWealth sources_of_income = 11;

  /*
     The origins of the client's total net worth or assets (e.g., inheritance, investments).
     This is distinct from the source of income.
     Required for verification.
  */
  repeated meshtrade.compliance.client.v1.SourceOfIncomeAndWealth sources_of_wealth = 12;

  /*
     The client's tax residency information, required for CRS/FATCA reporting.
     A client can be a tax resident in multiple jurisdictions.
     Required for verification.
  */
  repeated meshtrade.compliance.client.v1.TaxResidency tax_residencies = 13;
}