Qualify 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

ParameterTypeConcerned investor typeRequired forDescription
token_idThe identifier of the T-REX
JWTA valid authentication token of an agent on this token
investor_typeMUST be either individual or institutionIndividual and institutionIndividual and institutionThe type of investor.
first_namestringIndividualIndividualThe first name of the investor.
last_namestringIndividualIndividualThe last name of the investor.
genderMUST be either Male or Female.IndividualThe gender of the investor.
dobDates 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).IndividualIndividualThe date of birth of the investor.
pobstringIndividualThe country of birth of the investor.
nationalityISO 3 letter format.IndividualIndividualThe nationality of the investor.
id_card_numberstringIndividualIndividual (mandatory if not passport_number provided).The number of the identity card of the investor.
passport_numberstringIndividualIndividual (mandatory if no id_card_number provided).The number of the passport of the investor.
ssn_numberstringIndividualSocial Security Number of the investor.
phone_numberstring, 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.IndividualThe phone number of the investor.
occupationstringIndividualThe occupation of the investor
email_addressemailIndividualIndividualThe email address of the investor. This is the unique identifier for individual investors.
commercial_namestringInstitutionInstitutionThe commercial name of the investor.
legal_namestringInstitutionInstitutionThe legal name of the entity.
national_registration_numberstringInstitutionInstitutionThe registration number of the entity.
legal_formstringInstitution
incorporation_DateDates 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).InstitutionThe incorporation date of the entity.
sector_activitystringInstitutionThe 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_incorporationISO 3 letter format.InstitutionInstitutionThe country of incorporation.
admin_first_namestringInstitutionInstitutionThe first name of the administrator of the entity.
admin_last_namestringInstitutionInstitutionThe last name of the administrator of the entity.
admin_email_addressstringInstitutionInstitutionThe email of the administrator of the entity. This is the unique identifier for institutional investors.
pep_statusY/NIndividual and institutionThe pep status of the investor.
building_numberstringIndividual and institutionThe number of the building of the investor.
street_namestringIndividual and institutionIndividual and institutionThe name of the street of the building of the investor.
zip_codestringIndividual and institutionIndividual and institutionThe zip code of the building of the investor.
statestringIndividual and institutionThe state of the building of the investor.
citystringIndividual and institutionIndividual and institutionThe city of the building of the investor. - Concerned investor type: both individual and institution.
CountryISO 3 letter format.Individual and institutionIndividual and institutionThe country of the investor in ISO format.
kyc_aml_statusY/NIndividual and institutionIndividual and institutionIndicates if you did the KYC/AML validation of the investor.
onchainid_tcsY/NIndividual and institutionIndividual and institutionIndicates that you submitted the T&Cs of ONCHAINID to the investor, and they agree to them.
wallet_addressWallet addressIndividual and institutionIndividual and institutionThe 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.

ParameterTypeConcerned investor typeRequired forDescription
token_idThe identifier of the T-REX
jwtA valid authentication token of an agent on this token
identityIdsidentityIds validation is performedIndividual and institutionIndividual and institutionThe array of identities to whitelist, as retrieved after import
walletsbasic wallet validation is performedIndividual and institutionIndividual and institutionThe 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.