HomeDocumentationAPI Endpoints
We are hiring!

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. It is a two-step operation on the T-REX Servicing but it is actually a composition of several blockchain operations:

  • Creation of the investor identity and emission of the ONCHAINID
  • Issuance of the required claim of the T-REX on the ONCHAINID
  • Registering of the ONCHAINID in the T-REX Identity Registry

Authentication

cURL request

The first thing you need to use the T-REX Servicing API is to retrieve an authentication token that will allow you to retrieve the data. To do so, simple call the signin endpoint.

curl --request POST \
  --url https://servicing-api-staging.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: The authentication 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. - 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.
    • Values: "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. - 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 wallet address of the investor. - Concerned investor type: both individual and institution. Mandatory for: both individual and institution

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.

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: The authentication token
  • identityIds: The array of identities to whitelist, as retrieved after import.
  • wallets: The addresses of the wallets linked to the identities.
    If you wish to generate an ONCHAINID wallet for one of the identities, leave this entry to null (index of the wallet should match the index of the identityId)

Response

As a response, you will receive the following structure accompanied with a HTTP 202 code.

Troubleshooting

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

Updated 5 days ago