Qualifying investors

The qualification of investors is the action of rendering an investor, through their wallet and email addresses, eligible for receiving T-REX Tokens. This is required for any investor wanting to hold any specific security token, in the primary or secondary market.

Qualifying investors is a two-step operation on the T-REX Servicing, but it is actually a composition of several blockchain operations:

In case of a new investor; creation of the investor's identity in our backend and emission of the ONCHAINID
Issuance of the required claim of the T-REX token, on the ONCHAINID
Registering of the ONCHAINID in the T-REX Identity Registry (please refer to the ERC3643 whitepaper for any doubts)

📘
Prerequisites:
To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

Make sure to leverage an existing account, e.g. Agent, Owner, etc.

Sign into your Servicing portal to disable your 2FA.

Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.

Add the JWT to the header of your request.

Qualify investors

Fields can be mandatory or not mandatory. They can be requested for individuals and/or institutions.

It is possible to always send all the fields, regardless of investor type; to do so, please add "null" in the value of unneeded fields.

cURL request

curl -XPOST 'https://api-testing.tokeny.com/servicing/api/tokens/:token_id/import-investors' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  --data-binary '{
   "holdersArray":[
      {
         "Type":"<investor_type>",
         "First Name":"<first_name>",
         "Last Name":"<last_name>",
         "Gender":"<gender>",
         "Date of Birth":"<dob>", // example: 25/01/1970
         "Place of Birth":"<pob>",
         "Nationality":"<nationality>", // ISO
         "National ID Card #":"<id_card_number>",
         "Passport #":"<passport_number>",
         "SSN #":"<ssn_number>",
         "Phone Number":"<phone_number>",
         "Occupation":"<occupation>",
         "E-mail Address":"<email_adress>",
         "Commercial Name":"<commercial_name>",
         "Legal Name":"<legal_name>",
         "National Registration #":"<national_registration_number>",
         "Incorporation Date":"<incorporation_date>", // example: 01/01/2020
         "Sector of Activity":"<sector_activity>",
         "Country of Incorporation":"<country_incorporation>", // ISO
         "Admin Person First Name":"<admin_first_name>",
         "Admin Person Last Name":"<admin_last_name>",
         "Admin Person E-mail":"<admin_email_address>",
         "PEP":"<pep_status>", // Y or N
         "Building Number":"<building_number>",
         "Street":"<street_name>",
         "Zip Code":"<zip_code>",
         "State":"<state>",
         "City":"<city>",
         "Country":"<country>", // ISO
         "KYC/AML":"<kyc_aml_status>", // Y or N
         "ONCHAINID T&Cs":"<onchainid_tcs>", // Y or N
         "Wallet Address":"<wallet_address>"
      }
   ]
}'

Parameters

Parameter	Type	Concerned investor type	Required for	Description
token_id				The identifier of the T-REX
JWT				A valid authentication token of an agent on this token
investor_type	MUST be either `individual` or `institution`	Individual and institution	Individual and institution	The type of investor.
first_name	string	Individual	Individual	The first name of the investor.
last_name	string	Individual	Individual	The last name of the investor.
gender	MUST be either `Male` or `Female`.	Individual		The gender of the investor.
dob	Dates in the format day/month/year are accepted and will be converted to the standard date-time format as defined in the JSON Schema specification (ISO 8601), including the time zone (e.g., 1963-06-19T08:30:06.283185Z).	Individual	Individual	The date of birth of the investor.
pob	string	Individual		The country of birth of the investor.
nationality	ISO 3 letter format.	Individual	Individual	The nationality of the investor.
id_card_number	string	Individual	Individual (mandatory if not passport_number provided).	The number of the identity card of the investor.
passport_number	string	Individual	Individual (mandatory if no id_card_number provided).	The number of the passport of the investor.
ssn_number	string	Individual		Social Security Number of the investor.
phone_number	string, length between 5 and 25 characters. Must include the "+", followed by the international calling code. e.g. "+33672809090". No spaces or other chars are allowed. Based on the country code, the phone number must adhere to the corresponding country length and format rules: we first verify the phone number's length, then validate its digits using country-specific validations.	Individual		The phone number of the investor.
occupation	string	Individual		The occupation of the investor
email_address	email	Individual	Individual	The email address of the investor. This is the unique identifier for individual investors.
commercial_name	string	Institution	Institution	The commercial name of the investor.
legal_name	string	Institution	Institution	The legal name of the entity.
national_registration_number	string	Institution	Institution	The registration number of the entity.
legal_form	string	Institution
incorporation_Date	Dates in the format day/month/year are accepted and will be converted to the standard date-time format as defined in the JSON Schema specification (ISO 8601), including the time zone (e.g., 1963-06-19T08:30:06.283185Z).	Institution		The incorporation date of the entity.
sector_activity	string	Institution		The sector of activity number of the entity. While any valid value is accepted, here are some illustrative examples: "Advertising", "Aeronautics, Aerospace and Defense", "Agribusiness", "Agriculture", "Airlines", "Appliances", "Automobile Manufacturers", "Bank", "Brewery", "Building, construction and public works", "Catering", "Cement", "Chemistry", "Computer equipment", "Confectionery", "Consumer Consumption", "Consumer Electronics", "Cosmetics", "Cruises", "DIY", "Dairy products", "Distribution", "Electricity companies", "Electrical equipment", "Energy", "Entertainment", "Entertainment & Media", "Finance", "Health", "Heavy industry (excluding energy)", "Information and Communication Technologies", "Insurance", "IT technologies and services", "Large distribution", "Luxury", "Medical equipment and health products", "Mining activities", "Mobile phones", "Music Production (Majors)", "Oil companies", "Pharmacy", "Post, mail and deliveries", "Programming & Software", "Rail transport", "Seeds", "Shipping of goods", "Sporting equipment manufacturers", "Telecommunication and Network Equipment Manufacturers", "Telecommunications operators", "Tires", "Tobacco", "Traders", "Transportation", "Wind turbine manufacturers".
country_incorporation	ISO 3 letter format.	Institution	Institution	The country of incorporation.
admin_first_name	string	Institution	Institution	The first name of the administrator of the entity.
admin_last_name	string	Institution	Institution	The last name of the administrator of the entity.
admin_email_address	string	Institution	Institution	The email of the administrator of the entity. This is the unique identifier for institutional investors.
pep_status	Y/N	Individual and institution		The pep status of the investor.
building_number	string	Individual and institution		The number of the building of the investor.
street_name	string	Individual and institution	Individual and institution	The name of the street of the building of the investor.
zip_code	string	Individual and institution	Individual and institution	The zip code of the building of the investor.
state	string	Individual and institution		The state of the building of the investor.
city	string	Individual and institution	Individual and institution	The city of the building of the investor. - Concerned investor type: both individual and institution.
Country	ISO 3 letter format.	Individual and institution	Individual and institution	The country of the investor in ISO format.
kyc_aml_status	Y/N	Individual and institution	Individual and institution	Indicates if you did the KYC/AML validation of the investor.
onchainid_tcs	Y/N	Individual and institution	Individual and institution	Indicates that you submitted the T&Cs of ONCHAINID to the investor, and they agree to them.
wallet_address	Wallet address	Individual and institution	Individual and institution	The self-managed wallet address of the investor.

Response

{
   "holdersArray":[
      {
         "typeOfInvestor":"<investor_type>",
         "individualOrInstitution":"<individual_or_institution>",
         "firstName":"<first_name>",
         "lastName":"<last_name>",
         "gender":"<gender>",
         "birthday":"<dob>",
         "birthplace":"<pob>",
         "nationality":"<nationality>",
         "idNumber":"<id_card_number>",
         "passportNumber":"<passport_number>",
         "ssnNumber":"<ssn_number>",
         "phone":"<phone_number>",
         "occupation":"<occupation>",
         "email":"<email_address>",
         "institutionTradeName":"<commercial_name>",
         "institutionLegalName":"<legal_name>",
         "institutionRegistryNumber":"<registry_number>",
         "institutionLegalForm":"<legal_form>",
         "institutionIncorporationDate":"<incorporation_date>",
         "institutionActivity":"<institution_activity>",
         "institutionRegistryCountry":"<country_registration>",
         "politicallyExposed":"<pep_status>",
         "buildingNumber":"<building_number>",
         "street":"<street_name>",
         "zipCode":"<zip_code>",
         "state":"<state>",
         "city":"<city>",
         "country":"<country>",
         "kycAml":"<kyc_aml_status>",
         "onchainidTCs":"<onchainid_tcs>",
         "wallet":"<wallet_address>",
         "holderId":"<holder_id>",
         "result":"Success: Identity imported/updated."
      }
   ]
}

holderId: The offchain identifier of the holder in the Servicing App
result: The status of the import

Troubleshooting

{
   "statusCode":400,
   "timestamp":"2020-12-08T17:17:00.866Z",
   "path":"/api/tokens/0051545e-c104-48af-8acc-c936ab0d5255/import-investors",
   "errors":[
      {
         "email":"[email protected]",
         "result":"Error: Account creation error."
      },
      {
         "email":"[email protected]",
         "result":"Error: Account creation error."
      }
   ],
   "message":"Import holders failed",
   "name":"REST_VALIDATION_ERROR"
}

The errors array will give you a list of all errors found in the input of your import. Consult the result field to get more information about the content of the error.

Whitelist investors

Once the investors have been uploaded, you need to whitelist them to perform the blockchain operations described above.

cURL request

curl 'https://api-testing.tokeny.com/servicing/api/tokens/:token_id/holders/whitelist' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json'
  --data-binary '{
   "ethereumNetwork":"MAINNET",
   "identityIds":[
      "<identity_id>"
   ],
   "wallets":[
      "<wallet_address>"
   ]
}
'

Parameters

Both arrays must have matching corresponding orders. The first identityId in the identityIds array must correspond to the first wallet in the wallets array, and so on.

Parameter	Type	Concerned investor type	Required for	Description
token_id				The identifier of the T-REX
jwt				A valid authentication token of an agent on this token
identityIds	identityIds validation is performed	Individual and institution	Individual and institution	The array of identities to whitelist, as retrieved after import
wallets	basic wallet validation is performed	Individual and institution	Individual and institution	The addresses of the self-managed wallets linked to the identities

Response

As a response, you will receive the following structure accompanied by an HTTP 202 code. A whitelisting_id will also be provided.

Troubleshooting

You will receive an HTTP 401 when the authentication is wrong.

📘Prerequisites:

Qualify investors

cURL request

Parameters

Response

Troubleshooting

Whitelist investors

cURL request

Parameters

Response

Troubleshooting

📘
Prerequisites: