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 institution.
When qualifying an institution, 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 | In date-time format - the standard format as defined in JSON Schema specification. It’s an ISO date string, including time zone (eg. 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 "+" and the international calling code. e.g. "+33690909090" | Individual | The phone number of the investor. | |
| occupation | string | Individual | The occupation of the investor | |
| email_address | 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 | string | 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 T-REX Servicingresult: 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
token_id: The identifier of the T-REXjwt: A valid authentication token of an agent on this tokenidentityIds: The array of identities to whitelist, as retrieved after importwallets: 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 about 24 hours ago