Skip to main content

End-to-End API Investment Experience with Securitize

  • Updated

If you’re using your own front end and want to fully integrate the Securitize Domain API to handle investments and token issuance — you’re in the right place! 🎉

This guide will walk you through all the steps needed to build an end-to-end investment experience using our APIs.

🚀 Steps to Complete an Investment

Here’s the full process:

  1. Create an Investor
  2. Create an Investment
  3. Set the Pledge Amount
  4. Create Transactions
  5. Allocate Tokens to the Investor
  6. Issue the Tokens

Let’s dive in! 👇

🧑‍💼 Create Investor

First, you need to register the investor using this API:

curl --location --request POST 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/detail' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "firstName": "{name}",
  "lastName": "{last}",
  "email": "{email}",
  "investorType": "individual|entity",
  "countryCode": "{countryCode}",
  "address": "{address}",
  "middleName": "{middleName}",
  "phoneNumber": "{phone}",
  "state": "{state}",
  "city": "{city}",
  "zipCode": "{zipCode}"
}'

👉 The API will return an externalId that uniquely identifies the investor.

💰 Create Investment

An investment record links the investor to the token and the investment round.

curl --location --request POST 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/{externalId}/investment' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "tokenId": "{tokenId}",
  "roundId": {roundId},
  "currencyIdentifier": "{currency}"
}'

How to Get Required IDs:

  • Get tokenId: 
GET /v1/domains/{domainId}/tokens/list
  • Get roundId: 
GET /v1/domains/{domainId}/tokens/{tokenId}/rounds/list
  • Get available currencies: 
GET /v1/domains/{domainId}/currencies/list

📄 Set Pledge Amount

Once the investment is created, set the pledge amount:

curl --location --request PUT 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/{externalId}/investment/pledged-amount' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "amount": {amount},
  "roundId": {roundId},
  "currencyIdentifier": "USD"
}'

💳 Create Transactions

Now, log the payment transaction:

curl --location --request POST 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/{externalId}/investment/transactions/detail' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "roundId": {roundId},
  "direction": "deposit",
  "amount": {amount},
  "externalTransactionConfirmation": "{transaction description}",
  "tokenId": "{tokenId}",
  "currencyIdentifier": "USD",
  "transactionTime": "yyyy-mm-ddThh:MM:ss.000Z"
}'

👉 You can list, update, or delete transactions later if needed.

🎯 Allocate Tokens to the Investor

Before issuance, you need to assign the tokens to the investor:

curl --location --request PATCH 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/{externalId}/token-info' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "tokenId": "{tokenId}",
  "roundTokensAssigned": {amount}
}'

This allocation holds the tokens for the investor until the issuance step.

🪙 Token Issuance

🔐 If Using Securitize as Transfer Agent

👉 Please review the official Transfer Agent process documentation for these cases.

🛠️ If Issuing Tokens Directly

If you’re not using Securitize as a Transfer Agent, you can issue tokens to the investor using this API:

curl --location --request POST 'https://public-api.{environment}.securitize.io/v1/domains/{domainId}/investors/{externalId}/issuances/detail' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey xxx:yyy' \
--data-raw '{
  "tokenId": "{tokenId}",
  "sourceType": "{treasury|wallet}",
  "issuanceDate": "yyyy-mm-ddThh:MM:ss.000Z",
  "issueAmount": {amount},
  "clearAfterIssuance": true,
  "tokenWalletId": {tokenWalletId},
  "reason": "{reason for issuance}"
}'

Important Notes:

  • sourceType:
    • wallet – if the tokens should be issued directly to the investor’s blockchain wallet.
    • treasury – if the tokens should remain in Securitize’s internal book-entry system (TBE).
  • clearAfterIssuance:
    If set to true, the locally allocated tokens will be cleared after issuance.

🔎 How to Get Wallet IDs: 

GET /v1/domains/{domainId}/investors/{externalId}/token-wallets/list?tokenId={tokenId}

Final Step: Signature Required

The issuance transaction will appear on the Signatures page for approval. You’ll need the issuer’s wallet address and private key to sign the transaction.

Once signed, the issuance will process on the blockchain — this can take a few minutes.

✅ Summary

You’ve now completed the full end-to-end API investment journey using Securitize’s Domain API:

  • Register investor ✔️
  • Create investment ✔️
  • Set pledge ✔️
  • Log transactions ✔️
  • Allocate tokens ✔️
  • Issue tokens ✔️

 

Related articles