DocumentationAPI Endpoints
Documentation
Tokeny.com

Qualify new investors

Suggest Edits

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)

Authentication

cURL request

To leverage the T-REX Servicing API, you will first need to retrieve an authentication token that will allow you to perform this operation. For this use case, please make sure to get an authentication token corresponding to an agent account. If any doubts, please refer to our guide on permissions and roles.

In the testing environment, call the following signin endpoint:

curl --request POST \
  --url https://servicing-api-testing.tokeny.com/api/auth/signin \
  --header 'Content-Type: application/json' \
  --data '{"email":"[email protected]","password":"MyP@$$word"}'

Response

{
    "token": "<jwt>"
}

Qualify investors

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

When qualifying an institution, please add "null" in the value of unneeded fields.

cURL request

curl -XPOST 'https://servicing-api-staging.tokeny.com/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

  • token_id: The identifier of the T-REX
  • jwt: A valid authentication token of an agent on this token
  • investor_type: The type of investor. MUST be either individual or institution. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • first_name: The first name of the investor. - Concerned investor type: individual. Mandatory
  • last_name: The last name of the investor. - Concerned investor type: individual. Mandatory
  • gender: The gender of the investor. MUST be either Male or Female. - Concerned investor type: individual. Not Mandatory
  • dob: The date of birth of the investor. - Concerned investor type: individual. Mandatory
  • pob: The country of birth of the investor. - Concerned investor type: individual. Not Mandatory
  • nationality: The nationality of the investor. - Concerned investor type: individual. Mandatory
  • id_card_number: The number of the identity card of the investor. - Concerned investor type: individual. Mandatory if no passport_number provided
  • passport_number: The number of the passport of the investor. - Concerned investor type: individual. Mandatory if no id_card_number provided
  • ssn_number: Social Security Number of the investor. - Concerned investor type: individual. Not Mandatory
  • phone_number: The phone number of the investor. - Concerned investor type: individual. Not Mandatory
  • occupation: The occupation of the investor. - Concerned investor type: individual. Not Mandatory
  • email_address: The email address of the investor. This is the unique identifier for individual investors. - Concerned investor type: individual. Mandatory
  • commercial_name: The commercial name of the investor. - Concerned investor type: institution. Mandatory
  • legal_name: The legal name of the entity. - Concerned investor type: institution. Mandatory
  • national_registration_number: The registration number of the entity. - Concerned investor type: institution. Mandatory
  • sector_activity: The sector of activity number of the entity. - Concerned investor type: institution. Not Mandatory.
    • 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: The country of incorporation. - Concerned investor type: institution. Mandatory
  • admin_first_name: The first name of the administrator of the entity. - Concerned investor type: institution. Mandatory
  • admin_last_name: The last name of the administrator of the entity. - Concerned investor type: institution. Mandatory
  • admin_email_address: The email of the administrator of the entity. This is the unique identifier for institutional investors. - Concerned investor type: institution. Mandatory
  • pep_status: The pep status of the investor. - Concerned investor type: both individual and institution. Mandatory for: none
  • building_number: The number of the building of the investor. - Concerned investor type: both individual and institution. Mandatory for: none
  • street_name: The name of the street of the building of the investor. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • zip_code: The zip code of the building of the investor. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • state: The state of the building of the investor. - Concerned investor type: both individual and institution. Mandatory for: none
  • city: The city of the building of the investor. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • Country: The country of the investor in ISO format. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • kyc_aml_status: Indicates if you did the KYC/AML validation of the investor. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • onchainid_tcs: Indicates if you gave the T&Cs of ONCHAINID to the investor and they agree to them. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution
  • wallet_address: 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 identifier of the holder in the T-REX Servicing
  • 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://servicing-api-staging.tokeny.com/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

  • token_id: The identifier of the T-REX
  • jwt: A valid authentication token of an agent on this token
  • identityIds: The array of identities to whitelist, as retrieved after import
  • wallets: 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.

Troubleshooting

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

Updated 2 months ago