1 of 100

Integration API Guide

concepts and flows

Getting Started

Rev. 27 June 2025

The Corastone platform is a distributed platform for digital securities lifecycle management, powered by a private and permissioned blockchain. All organizations that are part of this permissioned ecosystem run the same software (which is developed and distributed by Corastone) on their own Amazon Web Services (AWS) account. Each organization has an API integration point into the platform and can optionally have a set of web applications to be used as GUIs to interact with the platform.

Using This Guide

This Integration API Guide provides:

basic flows for API calls
a synopsis of each endpoint
a link to the OpenAPI spec for each endpoint
supporting content

Platform Roles and the Integration API

Multiple parties participate in transactions on the Corastone platform. For example, an asset manager and a fund administrator might make sequential calls to approve a posted balance. To clarify which calls are appropriate for which roles, we have added a prefix (using the following abbreviations) to the title of each method page.

Abbreviation

Meaning

Asset Manager - General Partners (GP) align with this role.

Fund Administrator

Inv

Investing Organization - Weath Manaagers (WM) align with this role.

Amendments to This Guide

Date

Description

General Concepts

About Flows

The flows presented in the first part of this guide summarize the order of operations for key tasks and the roles that perform each task. Because the steps and roles can depend on the investment vehicle being used, there is a separate section for each supported vehicle type.

See also Data Dictionary for details on required fields and validations.

API Topics

The following articles discuss topics common across the Integration API

Managing the securityId
Mapping Your IDs to Corastone IDs
Parent and Child Securities (Share Classes)
Documents and Files

Managing the securityId

About the Fund Identifier

The securityId is a 12-character alphanumeric code that uniquely identifies a security on the ledger. It has the following format

unique organization ID (5 characters)
random characters (7 characters)

Example: WM1A3ACD234A

The securityId is required for uniquely identifying the security of interest. Note the following when managing your securityIds:

Issuers have access to this identifier upon launching the security on the ledger. See .
For investing organizations and service providers (e.g., fund administrators), the securityId is returned after they are assigned to the security using .

Mapping Your IDs to Corastone IDs

How to Use Correlation IDs

To avoid the need to keep track of the unique identifiers for Corastone entities, you can map your internal identifiers to Corastone identifiers on the Corastone platform. Use correlationIDs to perform these mappings. You can use the correlationData structure to map your identifiers when you start the process of creating an entity, like an asset. You can use Add Correlation ID endpoints to map one or more identifiers after creating an entity. Once your identifiers are mapped to Corastone identifiers, you can use your identifiers to refer to entity in other endpoints.

The following entities can have correlation IDs:

Accounts
Advisors
Assets
Capital Calls
Custodians
Distributions
Files
Funds
Investors
Issuance Closes
Organizations
Tender Offers
Tender Requests
Transfers

Example: Mapping Identifiers When Creating an Asset

The schema for the Create Asset endpoint includes a correlationData structure:

Submitting your Create Asset call with a correlationId specified maps the two identifiers for the subscription for the life of the resulting asset, unless you remove the correlationId (Remove Asset Correlation ID).

The following table details this structure.

Property

Description

Example

correlationId

The identifiers to be mapped to the Corastone identifier (securityId).

MYID89647

broadcastToCounterparty

Flag to indicate whether to share each correlationId with platform counterparties who have access to the details of the subscription.

False

origin

The system that created the identifier listed in the correlationId field.

Backoffice-123

Example: Mapping Identifiers After Creating an Asset

After the initial subscription request is submitted (Create Asset), you can add mapped identifiers using the Add Asset Correlation ID enpoint in the Asset API. This endpoint provides the same elements as the correlationData structure detailed above.

Example: Using Mapped Identifiers

Once your identifier is mapped to the Corastone identifier, you can supply your identifier to work with the entity. For example, to fetch asset details where the correlationId is KFC001, you might use:

{{URL}}/external/v1/asset?correlationIdsFilter=KFC0001

Using an Asset Correlation ID in the assetID Path Parameter

If you want to submit an asset correlation ID in the assetID path parameter, you must include isAssetCorrelationID as a query parameter. For example, to request remediation for an asset using the asset correlation ID "abc123" as the identifier, you would need to use:

{{URL}}/external/v1/primary/asset/abc123/request-remediation?isAssetCorrelationID=TRUE

Using a Shared Correlation ID

When an organization broadcasts a correlation ID, counterparties can use the correlation ID. To include another organization's correlation ID, you must also provide the assetCorrelationOrgId=<org> parameter, where <org> is the identifier for the organization that published the correlation ID.

For example, to use "abc123" as a correlation ID broadcast by org456, you would need to use:

{{URL}}/external/v1/primary/asset/abc123/request-remediation?isAssetCorrelationID=TRUE&assetCorrelationOrgId=org456

Parent and Child Securities (Share Classes)

Understanding Parent/Child Securities

An offering that includes multiple fee-structure options can have “child securities.” Each child security has its own securityId. Each securityId rolls up into the parent security.

Operations that involve securities with multiple share classes include applicable share-class securityIds when distinctions need to be made among the child securities. For example, a tender offer might specify different numbers of shares for different share classes.

Documents and Files

Documents and Files on the Platform

There are two ways to upload a document to the Corastone platform:

via upload link as part of a transaction
via form-data using a local file

In both cases, the API returns the fileId to use when associating the document with assets or investors.

Via Upload Link

To include a new document with a new subscription request (Create Asset), the uploadData property specifies the type, extension, and a link to the document location.

The document link must be a URL. If you are working with a local document, use the Upload Document endpoint described in the next section.

Via Form-Data

To upload a local document directly to the platform without a link, you can use the Upload Document endpoint. In this case, you select the local file as a form-data parameter and specify the file type as a query parameter.

Obtaining an Access Token

Getting API Access

To enable access to Corastone from the application you are integrating:

Concatenate your Corastone clientId and clientSecret as follows:

clientId:clientSecret

Base64 encode the resulting string.
Call the token endpoint (POST <AuthURL>/oauth2/token) as follows:
1. Use the header to pass in the base64 encoded string: Authorization: Basic <encoded_string>
2. Provide the necessary scope. The description of each endpoint specifies the associated scope.
Here's an example of a scope submission: {“grant_type”: “client_credentials”, “scope”: “createSubscription remediateSubscription cancelSubscription confirmCompleting manageServiceProviders readExclusivityOptions manageExclusivityOptions readNAV readSubscription readIssuance readInvestor readAccount readLedger readTransactionData manageExternalClients manageTrade readTrade manageReferenceData manageOrgs readOrgs readIssuanceClose readIssuanceClose completeOffering createIdBooking manageIdBooking readErrors manageErrors readSequencer readIssuingLegalEntity "}
Use the issued token as the bearer token in the call to functional APIs.

Testing a Subscription Request with dryRun

Testing a Subscription Request

Setting dryRun to TRUE for the Create Asset endpoint causes the platform to run the data validations without creating an asset or storing data in the database and/or blockchain.

The dryRun option is useful for:

testing sample payloads during coding of an integration
providing advisors with a button that confirms the payload is complete and correct before proceeding with other steps in the subscription process, such as uploading documents

Because the only difference between running Create Asset with dryRun set to TRUE vs FALSE is the step of persisting the resulting objects to the database and blockchain, there is no need to execute a dryRun call before every Create Asset call.

Flows: For All Investment Vehicles

Flows That Are Common Across Investment Vehicles

The following flows apply to all investment vehicles:

initial fund/offering setup
transfers

Initial Fund/Offering Setup

A fund/offering needs to be in place on the platform before transactions can occur. Once a fund/offering is active, initial investments can proceed. By default, only investing organizations that have received and accepted assignment to the exclusivity list for a security are allowed to participate. The optional flow for adding a service provider, such as a fund administrator, is valid at any point before close.

The following table lists the necessary steps to perform the outlined tasks.

Task

How

AM - Create and Launch Offering

AM/FA - Add Investing Org to Fund

Inv - Accept Fund Assignment

Inv - Retrieve Fund Information

Optional Workflow

AM - Assign Fund Administrator (optional)

FA - Accept/Reject FA Assignment (optional)

Transfers

Transfers apply when:

A life event, such as death or divorce, results in the need to move shares to a different account.
An advisor moves to a different firm, requiring transfer of shares for those clients who choose to follow the advisor.

The Integration API refers to shares as assets.

The following table lists the necessary steps to perform the outlined tasks.

Task

How

Inv - Request Transfer (Receiving Org)

AM/FA - Approve Transfer

Inv - Allocate Assets (Sending Org)

AM/FA - Complete Transfer (Sending Org)

Flows: For Drawdown Funds (lpInterest)

Working with Dropdown Funds

The following flows apply to drawdown funds:

initial fund/offering setup (see )
transfers (see )
initial investments
capital calls
distributions

Initial Investments

The initial investments for a drawdown fund have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of accepted shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Capital Calls

If a drawdown fund is configured for capital calls, the event can be started by either the general partner or the fund administrator, and both parties must approve.

If there is no fund admin, then the general partner must still approve.

Task

How

Distributions

If a drawdown fund is configured for distributions, the event can be started by either the general partner or the fund administrator, and both parties must approve.

If there is no fund admin, then the general partner must still approve.

Task

How

Flows: Hedge Fund Capital Accounting (lpInterest)

Working with Hedge Funds

The following flows apply to hedge fund capital accounting:

initial fund/offering setup (see )
transfers (see )
initial investments
distributions

Initial Investments

The initial investments for a hedge fund have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of settled shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Distributions

If a hedge fund is configured for distributions, the event can be started by either the general partner or the fund administrator, and both parties must approve.

If there is no fund admin, then the general partner must still approve.

Task

How

Flows: For Registered Funds (equity)

Working with Registered Funds

The following flows apply to registered funds:

initial fund/offering setup (see )
transfers (see )
tender offer redemptions

Initial Investments

The initial investments for a registered fund have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of accepted shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Tender Offer Redemption

For managed funds, either the general partner or the fund admin can initiate the event. Both must approve.

For self-managed funds, the general partner's approval is required.

Task

How

Flows: For Limited Liability Company (llcUnitShare)

Working with LLC Funds

The following flows apply to limited liability companies:

initial fund/offering setup (see )
transfers (see )
initial investments
tender offer redemptions

Initial Investments

The initial investments have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of accepted shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Tender Offer Redemption

For managed funds, either the general partner or the fund admin can initiate the event. Both must approve.

For self-managed funds, the general partner's approval is required.

Task

How

Flows: For Limited Partnerships (lpUnit)

Working with LP Funds

The following flows apply to limited partnerships:

initial fund/offering setup (see Flows: For All Investment Vehicles)
transfers (see Flows: For All Investment Vehicles)

Initial Investments

The initial investments have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of accepted shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Inv - Create Asset (Lot)

AM - Reject Asset (Investment) AM - Mark Assets Batch as Accepted

Inv - Mark Assets Batch as Wired

AM/FA - Mark Assets Batch as Settled

AM/FA - Run Close

Flows: For Segregated Portfolio Companies (spcUnit)

Working with SPC Funds

The following flows apply to segrated portfolio companies:

initial fund/offering setup (see Flows: For All Investment Vehicles)
transfers (see Flows: For All Investment Vehicles)
initial investments

Initial Investments

The initial investments have the following flow, with securities issued when the Asset Manager or Fund Admin runs a close for a batch of accepted shares. This flow assumes that:

The investing org has been assigned to the fund.
The investing org has accepted that assignment.

The Integration API refers to the initial step in subscribing as "creating an asset."

Task

How

Inv - Create Asset (Lot)

AM - Reject Asset (Investment) AM - Mark Assets Batch as Accepted

Inv - Mark Assets Batch as Wired

AM/FA - Mark Assets Batch as Settled

AM/FA - Run Close

libraries

Inv - Create Asset (Lot)

The Integration API refers to the initial step in subscribing as "creating an asset." Throughout the API flows, an asset represents multiple shares, or a lot, of a given security.

Details

Synopsis

Important Notes

See for information on using orchestrationId and processId.
Use the dryRun option to check the submission for completeness and correctness without persisting the information.

AM - Reject Asset (Lot)

Throughout the API flows, an asset represents multiple shares, or a lot, of a given security. After an investor requests a subscription for a security, the asset manager can accept or reject it.

Details

Synopsis

Important Notes

See for information on using orchestrationId and processId.
The dryRun option is included in the response, but is not yet used for this method.

AM/FA - Reject Recall Asset (Lot)

Throughout the API flows, an asset represents multiple shares, or a lot, of a given security. If an investor recalls an asset, the asset manager or fund administrator can accept or reject the request.

Detail

Synopsis

AM/FA - Mark Assets Batch as Accepted

Details

Synopsis

AM/FA - Mark Assets Batch as Settled

Throughout the API flows, an asset represents multiple shares, or a lot, of a given security. Once the funds for multiple transactions have been transferred, you can mark the shares as settled.

Details

Synopsis

AM/FA - Decline Asset (Lot)

Throughout the API flows, an asset represents multiple shares, or a lot, of a given security. If funds for a transaction are not received, the asset manager/fund administrator can decline the shares.

Details

Synopsis

Important Notes

See for information on using orchestrationId and processId.
The dryRun option is included in the response, but is not yet used for this method.

AM/FA/Inv - Add Issuance Close Correlation ID

Use a correlation ID to associate external identifiers with platform IDs.

AM/FA/Inv - Get Asset Correlation IDs History

Details

Synopsis

AM/FA - Get File Details

A file is a document associated with a subscription.

Details

Synopsis

AM/FA/Inv - Get File Correlation IDs History

Details

Synopsis

AM/FA/Inv - Get Issuance Close Correlation IDs History

Details

Synopsis

AM/FA - Get Fees Template History

Details

Synopsis

Service Provider Management

Managed funds may require fund administrators or other organizations to take part in tasks associated with offerings, capital events, and tender offers (redemptions). For the purposes of the Corastone platform, these organizations are considered service providers. Service providers have an official organization defined for them on the Corastone platform.

Initial Fund Setup (see optional steps)

Endpoints

The following list summarizes the primary endpoints required to support service provider management within the fund/offering life cycle:

Assign Service Provider to Offering

Accept Assignment to Offering

Reject Assignment to Offering

Remove Service Provider from Offering

Getters

Get Pending Assignments

Get Assigned Service Providers

See for information on using orchestrationId and processId.

AM/FA - Get Capital Event History

Details

Synopsis

AM/FA/Inv - Get Capital Event Correlation ID History

Details

Synopsis

NAV Reporting

Net asset value (NAV) records provide the per-share market values by date for fund share classes.

Endpoints

The following list summarizes the primary endpoints required to support the NAV reporting life cycle:

Getters

AM/FA - Delete NAV Unitized

Details

Synopsis

AM/FA - Get NAV Time Series

Details

Synopsis

AM - Add Organization to Exclusivity List

Details

/external/v1/exclusivity/add

Synopsis

Important Notes

This should only be triggered either by the organization that owns the security or by a channel admin.
securityId: uniquely identifies the fund/offering. See Managing the SecurityId.
See Blockchain Transaction Tracking for information on using orchestrationId and processId.

Get Security Details

get

This route is used to retrieve the details of securities given a set of search filters.

This endpoint is paginated, up to 10 records can be retrieved per call.

This endpoint can be called by applications with access to scope "readIssuance".

Authorizations

Query parameters

pageSizenumberOptional

The number of rows being retrieved. Must be a positive integer.

offsetnumberOptional

The offset (i.e. row start index). Must be a positive integer (or 0).

securityStatusFilterstringOptional

The comma delimited list of statuses to filter the security records. Up to 14 entries can be provided. Available values: deleted, preSync, active, closed, completed, bust_in_progress, busted, cancel_in_progress, canceled, refund_in_progress, retired, approved_revert_to_active, paused, archived

Example: active,closed

securityTypeFilterstringOptional

The comma delimited list of security types to filter the security records. Up to 7 entries can be provided. Available values: equity, lpUnits, llcUnits, spcUnits, convertible, lpInterest, llcUnitShares

Example: equity,llcUnitShares

securityIdsFilterstringOptional

The comma delimited list of security ids to filter the security records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

securityCorrelationIdsFilterstringOptional

The comma delimited list of security correlation ids to filter the security records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

securityCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "securityCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

Responses

200

Successfully retrieved the Issuance details

application/json

400

The following error codes can be returned: - GN0002 - GN0004 - GN0005 Please refer to the error code dictionary for the details of each error code.

application/json

401

The following error codes can be returned: - AU0001 Please refer to the error code dictionary for the details of each error code.

application/json

403

The following error codes can be returned: - AU0002 Please refer to the error code dictionary for the details of each error code.

application/json

get

GET /external/v1/securities HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "extraData": {
      "externalId": "123456789",
      "some": "Custom Property"
    },
    "name": "Test U.S. Real Estate Fund II Access Fund, L.P.",
    "shortName": "Test Real Estate Fund II",
    "externalIdentifiers": {
      "isin": "US0004026250",
      "cusip": "056833100",
      "ticker": "NYSE"
    },
    "settings": {
      "bankAccount": {
        "bankABA": "979384247",
        "bankName": "Test Bank",
        "accountName": "Test U.S. Real Estate Fund II Access Fund, L.P.",
        "accountNumber": "457349587349587"
      }
    },
    "securityId": "USCCWSF01I01",
    "isMoneyMarket": true,
    "termSheetInfo": {
      "securityType": "lpUnits",
      "campaignType": "NonContingent",
      "allowBelowMinimum": true,
      "mannerOfSaleInfo": {
        "endDate": "2024-09-12T00:00:00.000Z",
        "maxAmount": 750000000,
        "minAmount": 0,
        "startDate": "2024-09-12T00:00:00.000Z"
      },
      "regulation": "RegS",
      "priceOptions": {
        "unitized": false,
        "unitPrice": 12,
        "minimumInvestment": 120,
        "allowsReinvestment": true,
        "type": "static",
        "currency": "USD",
        "totalSold": 0
      },
      "navOptions": {
        "navCurrency": "USD",
        "navFrequency": "Monthly"
      },
      "dividendOptions": {
        "dividendOption": "Mandatory Dividend",
        "dividendPercentage": 3,
        "dividendPaymentSchedule": "Annually",
        "dividendType": "cumulative"
      },
      "redemptionOptions": {
        "redemptionTenderOfferOptionEnabled": true,
        "redemptionPercentage": 2,
        "redemptionFrequency": "Monthly",
        "redemptionLockupPeriodMonth": 30,
        "redemptionNoticePeriod": 10
      },
      "shareClassInfo": [
        {
          "securityId": "USCCWSF01I01",
          "correlationData": [
            {
              "correlationId": "123245573717",
              "origin": "Identifies share class on backoffice",
              "organization": {
                "name": "Test Organization",
                "orgId": "TEST1234"
              },
              "extraData": {
                "some": "Custom Property"
              }
            }
          ]
        }
      ],
      "feesInfo": {
        "feesTemplateInfo": {
          "feesTemplateId": "FT123456",
          "name": "Charles Schwab Fees Template",
          "status": "created",
          "backendFee": 0,
          "managementFees": [
            {
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 2,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 1.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            }
          ],
          "investorServicingFees": [
            {
              "maxAmount": 9999.99,
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 3,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 2.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            },
            {
              "minAmount": 10000,
              "maxAmount": 49999.99,
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 2,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 1.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            }
          ],
          "otherFees": [
            {
              "groupName": "Global fees",
              "groupDetails": [
                {
                  "feesInfo": [
                    {
                      "description": "Some global fee",
                      "value": 75,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                }
              ]
            },
            {
              "groupName": "Bank fees",
              "groupDetails": [
                {
                  "maxAmount": 4999.99,
                  "feesInfo": [
                    {
                      "description": "Bank fees - tier 1 - $5,000,000 - $9,999,999",
                      "value": 50,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                },
                {
                  "minAmount": 5000,
                  "maxAmount": 999999.99,
                  "feesInfo": [
                    {
                      "description": "Bank fees - tier 2 - $10,000,000+",
                      "value": 25,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                }
              ]
            }
          ]
        },
        "commonFees": {
          "performanceFees": {
            "hurdleRate": 1,
            "highWatermark": {
              "enabled": true,
              "frequency": "Quarterly"
            },
            "grossOrNet": "Net",
            "fees": [
              {
                "description": "The performance fee details during the IP period",
                "value": 1,
                "unit": "percentage",
                "frequency": "Annually"
              },
              {
                "description": "Some other description about the fee structure in the Post-IP period",
                "value": 0.5,
                "unit": "basisPoints",
                "frequency": "Semi-Annually"
              }
            ]
          }
        }
      }
    },
    "campaignCompletedDate": "2024-09-12T00:00:00.000Z",
    "restricted": false,
    "exemption": "REIT",
    "parentSecurityId": "USCCWSF01I01",
    "exclusivityType": "private",
    "status": "active",
    "shareClassOptions": {
      "description": "This share class is offered to brokerage accounts",
      "accountEligibility": "Brokerage"
    },
    "accountId": "US9QIMAOAS1Q",
    "organization": {
      "orgId": "TEST1234",
      "name": "Test Organization"
    },
    "deploymentStatus": "success",
    "locked": false,
    "legalEntityInfo": {
      "legalEntityId": "US1G14EGN",
      "status": "preSync",
      "locked": false,
      "name": "Test Legal Entity",
      "type": "LP",
      "taxId": "987654321",
      "address": {
        "addressLineOne": "8 Greenway Plaza",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zipCode": "10165"
      },
      "isUsEntity": true,
      "contactInfo": [
        {
          "email": "[email protected]",
          "phoneNumber": "+1234950987"
        }
      ],
      "incorporationDate": "2024-09-12",
      "incorporationState": "DE",
      "incorporationCountry": "US",
      "fundInfo": {
        "name": "Test Fund",
        "description": "This data is for test purposes",
        "taxReporting": "K-1",
        "exemption": "3(C)(1)",
        "type": "Hedge Fund",
        "strategy": "Long/Short",
        "is1031Eligible": false
      }
    },
    "correlationData": [
      {
        "correlationId": "123245573717",
        "origin": "Identifies security on backoffice",
        "organization": {
          "name": "Test Organization",
          "orgId": "TEST1234"
        },
        "extraData": {
          "some": "Custom Property"
        }
      }
    ]
  }
]

Add Organization to Exclusivity Offering List

post

This route is used to add an organization to the exclusivity list. This will enable that organization to invest in this security.

This should only be triggered by the organization that owns the security.

It triggers an asynchronous process that will persist this information on the blockchain, which can be monitored using the "Transactions API" endpoints.

This endpoint can be invoked by organizations that have at least one of the following roles on this security: ["issuer"].

This endpoint can't be invoked if the security is restricted.

This endpoint can be called by applications with access to scope "manageExclusivityOptions".

Authorizations

Body

transactionDataall ofRequired

This property contains the transactional data information, i.e. which is the security being affected by this action

Example: {"securityId":"USS3JKS01I00","signer":{"email":"[email protected]","name":"John Doe"}}

orgIdstring · max: 50Required

The id of the organization. Used to uniquely identify the organization on the ledger

Example: US9QIMA

isRepLetterProvidedbooleanOptional

Set this value to true if the issuer of the security has a rep letter from the distribution partner being assigned to the exclusivity list. It is an optional field with default value set to false

Default: falseExample: true

feesTemplateDataall ofOptional

The exclusive offering's fees template details. If not provided, then new empty fees template will be created.

Example:

{"data":{"managementFees":[{"feesInfo":[{"description":"IP: annually of capital commitments | 6 years from the date of initial investment","value":2,"unit":"percentage","frequency":"Annually"},{"description":"Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options","value":1.5,"unit":"percentage","frequency":"Annually"}]}],"investorServicingFees":[{"maxAmount":9999.99,"feesInfo":[{"description":"IP: annually of capital commitments | 6 years from the date of initial investment","value":3,"unit":"percentage","frequency":"Annually"},{"description":"Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options","value":2.5,"unit":"percentage","frequency":"Annually"}]},{"minAmount":10000,"maxAmount":49999.99,"feesInfo":[{"description":"IP: annually of capital commitments | 6 years from the date of initial investment","value":2,"unit":"percentage","frequency":"Annually"},{"description":"Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options","value":1.5,"unit":"percentage","frequency":"Annually"}]}],"otherFees":[{"groupName":"Global fees","groupDetails":[{"feesInfo":[{"description":"Some global fee","value":75,"unit":"basisPoints","frequency":"One-Off"}]}]},{"groupName":"Bank fees","groupDetails":[{"maxAmount":4999.99,"feesInfo":[{"description":"Bank fees - tier 1 - $5,000,000 - $9,999,999","value":50,"unit":"basisPoints","frequency":"One-Off"}]},{"minAmount":5000,"maxAmount":999999.99,"feesInfo":[{"description":"Bank fees - tier 2 - $10,000,000+","value":25,"unit":"basisPoints","frequency":"One-Off"}]}]}]}}

Responses

201

Successfully triggered the process to add the new organization to the exclusive list of investing organizations. The "processId" and "orchestrationId" properties can be used on the "Transactions API" to monitor the status of this asynchronous process.

application/json

400

The following error codes can be returned: - GN0002 - IS0004 Please refer to the error code dictionary for the details of each error code.

application/json

401

The following error codes can be returned: - AU0001 - AU0003 Please refer to the error code dictionary for the details of each error code.

application/json

403

The following error codes can be returned: - AU0002 - OG0025 - OG0028 - IS0099 Please refer to the error code dictionary for the details of each error code.

application/json

404

The following error codes can be returned: - IS0009 - OG0001 Please refer to the error code dictionary for the details of each error code.

application/json

409

The following error codes can be returned: - IS0013 - IS0010 - IS0019 - IS0003 - IS0062 - IS0012 - EX0002 - EX0003 - EX0004 - EX0010 Please refer to the error code dictionary for the details of each error code.

application/json

post

POST /external/v1/exclusivity/add HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3763

{
  "transactionData": {
    "securityId": "USS3JKS01I00",
    "signer": {
      "email": "[email protected]",
      "name": "John Doe"
    }
  },
  "orgId": "US9QIMA",
  "isRepLetterProvided": true,
  "feesTemplateData": {
    "data": {
      "managementFees": [
        {
          "feesInfo": [
            {
              "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
              "value": 2,
              "unit": "percentage",
              "frequency": "Annually"
            },
            {
              "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
              "value": 1.5,
              "unit": "percentage",
              "frequency": "Annually"
            }
          ]
        }
      ],
      "investorServicingFees": [
        {
          "maxAmount": 9999.99,
          "feesInfo": [
            {
              "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
              "value": 3,
              "unit": "percentage",
              "frequency": "Annually"
            },
            {
              "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
              "value": 2.5,
              "unit": "percentage",
              "frequency": "Annually"
            }
          ]
        },
        {
          "minAmount": 10000,
          "maxAmount": 49999.99,
          "feesInfo": [
            {
              "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
              "value": 2,
              "unit": "percentage",
              "frequency": "Annually"
            },
            {
              "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
              "value": 1.5,
              "unit": "percentage",
              "frequency": "Annually"
            }
          ]
        }
      ],
      "otherFees": [
        {
          "groupName": "Global fees",
          "groupDetails": [
            {
              "feesInfo": [
                {
                  "description": "Some global fee",
                  "value": 75,
                  "unit": "basisPoints",
                  "frequency": "One-Off"
                }
              ]
            }
          ]
        },
        {
          "groupName": "Bank fees",
          "groupDetails": [
            {
              "maxAmount": 4999.99,
              "feesInfo": [
                {
                  "description": "Bank fees - tier 1 - $5,000,000 - $9,999,999",
                  "value": 50,
                  "unit": "basisPoints",
                  "frequency": "One-Off"
                }
              ]
            },
            {
              "minAmount": 5000,
              "maxAmount": 999999.99,
              "feesInfo": [
                {
                  "description": "Bank fees - tier 2 - $10,000,000+",
                  "value": 25,
                  "unit": "basisPoints",
                  "frequency": "One-Off"
                }
              ]
            }
          ]
        }
      ]
    }
  },
  "shareClassSecurityInfo": [
    {
      "shareClassId": "USS3JKS01I00",
      "feesTemplateData": {
        "data": {
          "maxFrontendFee": 1,
          "backendFee": 0,
          "managementFees": [
            {
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 2,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 1.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            }
          ],
          "investorServicingFees": [
            {
              "maxAmount": 9999.99,
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 3,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 2.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            },
            {
              "minAmount": 10000,
              "maxAmount": 49999.99,
              "feesInfo": [
                {
                  "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                  "value": 2,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                  "value": 1.5,
                  "unit": "percentage",
                  "frequency": "Annually"
                }
              ]
            }
          ],
          "otherFees": [
            {
              "groupName": "Global fees",
              "groupDetails": [
                {
                  "feesInfo": [
                    {
                      "description": "Some global fee",
                      "value": 75,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                }
              ]
            },
            {
              "groupName": "Bank fees",
              "groupDetails": [
                {
                  "maxAmount": 4999.99,
                  "feesInfo": [
                    {
                      "description": "Bank fees - tier 1 - $5,000,000 - $9,999,999",
                      "value": 50,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                },
                {
                  "minAmount": 5000,
                  "maxAmount": 999999.99,
                  "feesInfo": [
                    {
                      "description": "Bank fees - tier 2 - $10,000,000+",
                      "value": 25,
                      "unit": "basisPoints",
                      "frequency": "One-Off"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

{
  "processId": "2159457f-0167-4e93-a969-9cf0db05e0bf",
  "orchestrationId": "2159457f-0167-4e93-a969-9cf0db05e0bf"
}

Get Security History Details

get

This route is used to retrieve the history data entries of securities given a set of filters such as blockchain details or security identifiers.

The history entries will reflect the state of the securities on a particular block on the ledger.

This endpoint returns paginated data. Up to 10 can be extracted per call.

This endpoint can be called by applications with access to scope "readIssuance".

Authorizations

Query parameters

pageSizenumberOptional

The number of rows being retrieved. Must be a positive integer.

offsetnumberOptional

The offset (i.e. row start index). Must be a positive integer (or 0).

blockNumbernumber · max: 2147483647Optional

The block number where the action was recorded on the ledger.

Example: 350

transactionIdstring · max: 500Optional

The transaction id where the action was recorded on the ledger.

Example: 456789OIJHGFCVGHJKLKJHGF67JHPattern: ^[a-zA-Z0-9-]*$

channelNamestring · max: 20Optional

The name of the channel where the action was recorded on the ledger.

Example: OG123Pattern: ^[a-zA-Z0-9-]*$

securityIdsFilterstringOptional

The comma delimited list of security ids to filter the security history records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

securityCorrelationIdsFilterstringOptional

The comma delimited list of security correlation ids to filter the security history records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

securityCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "securityCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

Responses

200

Successfully retrieved the Security history

application/json

400

The following error codes can be returned: - GN0002 - GN0004 - GN0005 Please refer to the error code dictionary for the details of each error code.

application/json

401

The following error codes can be returned: - AU0001 Please refer to the error code dictionary for the details of each error code.

application/json

403

The following error codes can be returned: - AU0002 Please refer to the error code dictionary for the details of each error code.

application/json

get

GET /external/v1/securities/history HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "timestamp": "2024-09-12T00:00:00.000Z",
    "blockNumber": 350,
    "transactionId": "456789OIJHGFCVGHJKLKJHGF67JH",
    "channelName": "OG123",
    "event": "Created",
    "update": {
      "legalEntityInfo": {
        "legalEntityId": "US1G14EGN"
      },
      "securityId": "USCCWSF01I01",
      "termSheetInfo": {
        "securityType": "lpUnits",
        "campaignType": "NonContingent",
        "allowBelowMinimum": true,
        "mannerOfSaleInfo": {
          "endDate": "2024-09-12T00:00:00.000Z",
          "maxAmount": 750000000,
          "minAmount": 0,
          "startDate": "2024-09-12T00:00:00.000Z"
        },
        "regulation": "RegS",
        "priceOptions": {
          "unitized": false,
          "unitPrice": 12,
          "minimumInvestment": 120,
          "allowsReinvestment": true,
          "type": "static",
          "currency": "USD",
          "totalSold": 0
        },
        "navOptions": {
          "navCurrency": "USD",
          "navFrequency": "Monthly"
        },
        "dividendOptions": {
          "dividendOption": "Mandatory Dividend",
          "dividendPercentage": 3,
          "dividendPaymentSchedule": "Annually",
          "dividendType": "cumulative"
        },
        "redemptionOptions": {
          "redemptionTenderOfferOptionEnabled": true,
          "redemptionPercentage": 2,
          "redemptionFrequency": "Monthly",
          "redemptionLockupPeriodMonth": 30,
          "redemptionNoticePeriod": 10
        },
        "shareClassInfo": [
          {
            "securityId": "USCCWSF01I01",
            "correlationData": [
              {
                "correlationId": "123245573717",
                "origin": "Identifies share class on backoffice",
                "organization": {
                  "name": "Test Organization",
                  "orgId": "TEST1234"
                },
                "extraData": {
                  "some": "Custom Property"
                }
              }
            ]
          }
        ],
        "feesInfo": {
          "feesTemplateInfo": {
            "feesTemplateId": "FT123456",
            "name": "Charles Schwab Fees Template",
            "status": "created",
            "backendFee": 0,
            "managementFees": [
              {
                "feesInfo": [
                  {
                    "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                    "value": 2,
                    "unit": "percentage",
                    "frequency": "Annually"
                  },
                  {
                    "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                    "value": 1.5,
                    "unit": "percentage",
                    "frequency": "Annually"
                  }
                ]
              }
            ],
            "investorServicingFees": [
              {
                "maxAmount": 9999.99,
                "feesInfo": [
                  {
                    "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                    "value": 3,
                    "unit": "percentage",
                    "frequency": "Annually"
                  },
                  {
                    "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                    "value": 2.5,
                    "unit": "percentage",
                    "frequency": "Annually"
                  }
                ]
              },
              {
                "minAmount": 10000,
                "maxAmount": 49999.99,
                "feesInfo": [
                  {
                    "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
                    "value": 2,
                    "unit": "percentage",
                    "frequency": "Annually"
                  },
                  {
                    "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
                    "value": 1.5,
                    "unit": "percentage",
                    "frequency": "Annually"
                  }
                ]
              }
            ],
            "otherFees": [
              {
                "groupName": "Global fees",
                "groupDetails": [
                  {
                    "feesInfo": [
                      {
                        "description": "Some global fee",
                        "value": 75,
                        "unit": "basisPoints",
                        "frequency": "One-Off"
                      }
                    ]
                  }
                ]
              },
              {
                "groupName": "Bank fees",
                "groupDetails": [
                  {
                    "maxAmount": 4999.99,
                    "feesInfo": [
                      {
                        "description": "Bank fees - tier 1 - $5,000,000 - $9,999,999",
                        "value": 50,
                        "unit": "basisPoints",
                        "frequency": "One-Off"
                      }
                    ]
                  },
                  {
                    "minAmount": 5000,
                    "maxAmount": 999999.99,
                    "feesInfo": [
                      {
                        "description": "Bank fees - tier 2 - $10,000,000+",
                        "value": 25,
                        "unit": "basisPoints",
                        "frequency": "One-Off"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          "commonFees": {
            "performanceFees": {
              "hurdleRate": 1,
              "highWatermark": {
                "enabled": true,
                "frequency": "Quarterly"
              },
              "grossOrNet": "Net",
              "fees": [
                {
                  "description": "The performance fee details during the IP period",
                  "value": 1,
                  "unit": "percentage",
                  "frequency": "Annually"
                },
                {
                  "description": "Some other description about the fee structure in the Post-IP period",
                  "value": 0.5,
                  "unit": "basisPoints",
                  "frequency": "Semi-Annually"
                }
              ]
            }
          }
        }
      },
      "campaignCompletedDate": "2024-09-12T00:00:00.000Z",
      "restricted": false,
      "parentSecurityId": "USCCWSF01I01",
      "exclusivityType": "private",
      "status": "active",
      "shareClassOptions": {
        "description": "This share class is offered to brokerage accounts",
        "accountEligibility": "Brokerage"
      },
      "accountId": "US9QIMAOAS1Q",
      "organization": {
        "orgId": "TEST1234",
        "name": "Test Organization"
      },
      "deploymentStatus": "success",
      "name": "Test Security",
      "shortName": "Test Sec",
      "externalIdentifiers": {
        "isin": "US1234567890",
        "cusip": "US1234567890",
        "ticker": "US1234567890"
      },
      "settings": {
        "bankAccount": {
          "bankABA": "979384247",
          "bankName": "Test Bank",
          "accountName": "Test U.S. Real Estate Fund II Access Fund, L.P.",
          "accountNumber": "457349587349587"
        }
      }
    },
    "signerData": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "extraData": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "organization": {
      "name": "Test Organization",
      "orgId": "TEST1234"
    }
  }
]

Get Asset Details

get

This route is used to retrieve the details of assets, given a set of search filters.

This endpoint is paginated, up to 500 records can be retrieved per call.

This endpoint can be called by applications with access to scope "readSubscription".

Authorizations

Query parameters

pageSizenumberOptional

The number of rows being retrieved. Must be a positive integer.

offsetnumberOptional

The offset (i.e. row start index). Must be a positive integer (or 0).

assetStatusFilterstringOptional

The comma delimited list of statuses to filter the asset records. Up to 27 entries can be provided. Available values: deleted, preSynced, created, modified, confirmed, settlement_confirmation_pending, settled, issued, busted, canceled, disposed, recalled, remediated, remediation_pending, locked, trade_proposed, in_trade, in_trade_pending, in_transfer, in_transfer_pending, restricted, retired, refunded, in_tender, in_tender_pending, template, locked_for_redemption

Example: created,settled

securityIdsFilterstringOptional

The comma delimited list of security ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

securityCorrelationIdsFilterstringOptional

The comma delimited list of security correlation ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

assetIdsFilterstringOptional

The comma delimited list of asset ids to filter the asset records. Up to 500 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

assetCorrelationIdsFilterstringOptional

The comma delimited list of asset correlation ids to filter the asset records. Up to 50 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

accountIdsFilterstringOptional

The comma delimited list of account ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

accountCorrelationIdsFilterstringOptional

The comma delimited list of account correlation ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

securityCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "securityCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

accountCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "accountCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

assetCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "assetCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

modelAssetIdsFilterstringOptional

The comma delimited list of model asset ids to filter the asset records. Up to 500 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

investorIdsFilterstringOptional

The comma delimited list of investor ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

investorCorrelationIdsFilterstringOptional

The comma delimited list of investor correlation ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

investorCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "investorCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

closeIdsFilterstringOptional

The comma delimited list of close ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 12 characters.

Example: USCCWSF01I00,USCCWSF01I01

closeCorrelationIdsFilterstringOptional

The comma delimited list of close correlation ids to filter the asset records. Up to 10 records can be provided. Each record should not exceed 100 characters.

Example: 1234,5678,7890

closeCorrelationOrgIdstring · max: 12Optional

The organization identifier linked to the correlation ids provided in the "closeCorrelationIdsFilter" property. If not provided the organization id will be inferred from the access token.

Responses

200

Successfully retrieved asset details

application/json

400

The following error codes can be returned: - GN0002 - GN0004 - GN0005 Please refer to the error code dictionary for the details of each error code.

application/json

401

The following error codes can be returned: - AU0001 Please refer to the error code dictionary for the details of each error code.

application/json

403

The following error codes can be returned: - AU0002 Please refer to the error code dictionary for the details of each error code.

application/json

get

GET /external/v1/asset HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "extraData": {
      "externalId": "123456789",
      "some": "Custom Property"
    },
    "assetId": "US9QIMAOAS1Q",
    "modelAssetId": "USS3JKS01I00",
    "securityId": "USCCWSF01I00",
    "closeId": "USCCWSF01I00",
    "accountId": "US9QIMAOAS1Q",
    "acquiredDate": "2024-09-12T00:00:00.000Z",
    "disposedDate": "2024-09-12T00:00:00.000Z",
    "acquiredPrice": 100,
    "disposedPrice": 200,
    "issuedDate": "2024-09-12T00:00:00.000Z",
    "amount": 1000,
    "sharesNumber": 1000,
    "commission": 1000,
    "currentValue": 1200,
    "redemptionAmount": 500,
    "remediationProposal": {
      "amount": 500
    },
    "tenderProposal": {
      "sharesNumberSubmitted": 500,
      "sharesNumberAccepted": 500,
      "tradeId": "TEST1234"
    },
    "capitalCallDetails": {
      "calledAmount": 300000,
      "calledAmountOutsideCommitment": 5000,
      "distributedAmount": 10000,
      "enabled": true
    },
    "status": "issued",
    "shouldReinvest": false,
    "customCostBasis": false,
    "customCostBasisValue": 100,
    "completedByAdvisorId": "text",
    "subDocSignDate": "2024-09-12T00:00:00.000Z",
    "originatingTradeId": 345023,
    "fileIds": [
      "US9QIFILE1",
      "US9QIFILE2"
    ],
    "rejectReason": {
      "reason": [
        {
          "message": "reject reason",
          "category": "EC006",
          "documentWithIssues": [
            {
              "document": {
                "fileId": "FILE3JUS03I04"
              },
              "pages": [
                {
                  "pageNumber": 1,
                  "description": "The first page has an invalid signature"
                }
              ]
            }
          ]
        }
      ],
      "extraData": {
        "externalId": "123456789",
        "some": "Custom Property"
      }
    },
    "bookingModel": "fullyDisclosedFBO",
    "underlyingInvestorAccountId": "US9QIMAOAC3F",
    "fees": {
      "frontendFee": 1,
      "backendFee": 0,
      "managementFees": [
        {
          "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
          "value": 2,
          "unit": "percentage",
          "frequency": "Annually"
        },
        {
          "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
          "value": 1.5,
          "unit": "percentage",
          "frequency": "Annually"
        }
      ],
      "investorServicingFees": [
        {
          "description": "IP: annually of capital commitments | 6 years from the date of initial investment",
          "value": 3,
          "unit": "percentage",
          "frequency": "Annually"
        },
        {
          "description": "Post-IP: annually on invested capital (remaining cost) | 11 years from the initial investment with 2 one-year extension options",
          "value": 2.5,
          "unit": "percentage",
          "frequency": "Annually"
        }
      ],
      "otherFees": [
        {
          "groupName": "Global fees",
          "groupDetails": [
            {
              "description": "Some global fee",
              "value": 75,
              "unit": "basisPoints",
              "frequency": "One-Off"
            }
          ]
        },
        {
          "groupName": "Bank fees",
          "groupDetails": [
            {
              "description": "Bank fees - tier 1 - $5,000,000 - $9,999,999",
              "value": 50,
              "unit": "basisPoints",
              "frequency": "One-Off"
            }
          ]
        }
      ]
    },
    "type": "standard",
    "inputIds": [
      "US9QIMAOAS1Q"
    ],
    "organization": {
      "orgId": "TEST1234",
      "name": "Test Organization"
    },
    "correlationData": [
      {
        "correlationId": "123245573717",
        "origin": "Identifies security on backoffice",
        "organization": {
          "name": "Test Organization",
          "orgId": "TEST1234"
        },
        "extraData": {
          "some": "Custom Property"
        }
      }
    ],
    "ownerName": "<WeInvest Inc.> fbo \"John Doe, Jane Doe\"",
    "locked": false,
    "latestUpdateTimestamp": "2024-09-12T00:00:00.000Z"
  }
]

Create Digital Asset

post

This route is used to trigger the recording of a digital asset on the blockchain for a particular security. It is the first action that should be triggered to start the subscription flow.

This triggers an asynchronous process (the id of which is returned on the success response) which can be monitored using the "Transactions API" endpoints.

This asynchronous process will either be composed of 2 transactions - if the intention is bringing a new investor/account to the ledger, or updating an existing one - or just 1 transaction if this is a subsequent investment done from an existing investor/account without any change.

This endpoint can be invoked if the security is in one of the following statuses: ["active"].

This endpoint can be invoked by organizations that have at least one of the following roles on this security: ["investor"].

This endpoint can't be invoked if the security is restricted.

This endpoint can be called by applications with access to scope "createSubscription".

Authorizations

Body

accountall ofRequired

This property contains the reference data of the account that holds the digital security.

Example:

{"correlationData":[{"correlationId":"INV001"}],"data":{"name":"Individual Account","type":"Individual","relationshipType":"Brokerage","bankAccount":{"accountNumber":"111111111","accountName":"savings account","bankABA":"555555555","bankName":"Test Bank","bankSwift":"AAAA-BB-CC-123","extraData":{"settlementInstructions":"Please wire the amount within 72 hours","some":"Other Property"}},"contactInfo":[{"email":"[email protected]","phoneNumber":"832-426-4242","type":"primary"},{"email":"[email protected]","phoneNumber":"987-564-1234","type":"tax","name":"John Doe","description":"Use this contact for Tax Related Information (K-1, 1099 or other tax related information)"}],"custodian":{"data":{"name":"Charles Schwab"}},"advisors":[{"data":{"type":"FA","name":"Chris Smith","crdCode":"546321","repCode":"AB98765"}}],"authorizedSigners":[{"name":"Jane Doe","primary":true,"extraData":{"externalId":"123456","some":"Other Property"}}],"beneficiaries":[{"name":"John Doe","beneficialOwnership":40,"individualInfo":{"name":"John Doe","taxId":"123456789"}},{"name":"Jane Doe LLC","beneficialOwnership":60,"legalEntityInfo":{"name":"Jane Doe Private Investments and Capital Management, LLC","type":"LLC","taxId":"987654321"}}],"secureExtraData":{"sensitive":"Data to be protected by application encryption"}}}

transactionDataall ofRequired

This property contains the transactional data information, i.e. which is the security being bought and the investment details

Example: {"securityId":"USS3JKS01I00","amount":50000,"signer":{"email":"[email protected]","name":"John Doe"}}

bypassFileDataValidationbooleanOptional

Set this to true if you want to bypass file data consistency (e.g. W9 data matching the investor/account information being provided)

Example: true

dryRunbooleanOptional

Set this to true if you want the request to go through the typical request validation stages up until persisting objects to database. If this is set to true then no data will actually be persisted neither on the database nor the blockchain, and no data will be sent out to the issuer, but all the request validations will be executed.

A typical use case for this would be for an advisor to check that a subscription being created for a particular client is valid prior to actually sending it out.

Default: falseExample: true

Responses

201

Successfully triggered the process to record the digital asset on the ledger (and publish a new or an updated investor/account to the ledger depending on the input payload) The "processId" and "orchestrationId" properties can be used on the "Transactions API" to monitor the status of this asynchronous process. The "assetId" property can be used on the "Assets API" to get the details of the digital asset.

application/json

400

The following error codes can be returned: - GN0002 - IS0008 - IS0106 - IS0001 - AS0009 - IV0006 - IV0007 - IV0009 - IV0008 - IV0020 - IV0021 - IV0022 - IV0017 - IV0016 - IV0023 - IV0035 - IV0032 - IV0036 - IV0037 - IV0017 - AC0006 - AC0007 - AC0013 - AC0014 - AC0016 - AC0017 - AC0049 - AC0044 - AC0050 - AD0017 - AD0016 - AD0018 - AD0022 - AD0023 - CT0015 - CT0017 - CT0019 - CT0020 - AS0016 - AS0029 - FL0002 - FL0003 - FL0019 - FL0004 - FL0005 - FL0017 - FL0020 - QU0001 - QU0002 - QU0003 - QU0004 - QU0005 - QU0006 - QU0007 - QU0008 - QU0009 - QU0010 - CI0001 - CI0002 - CI0003 - CI0004 Please refer to the error code dictionary for the details of each error code.

application/json

401

The following error codes can be returned: - AU0001 - AU0003 Please refer to the error code dictionary for the details of each error code.

application/json

403

The following error codes can be returned: - AU0002 - EX0006 - AC0020 - IV0013 - AD0012 - CT0011 - IS0099 Please refer to the error code dictionary for the details of each error code.

application/json

404

The following error codes can be returned: - IS0009 - GN0008 - IV0002 - AC0002 - FL0008 Please refer to the error code dictionary for the details of each error code.

application/json

409

The following error codes can be returned: - IS0012 - IS0013 - IS0026 - IS0027 - IS0028 - IS0029 - IS0030 - IS0034 - AS0017 - IV0003 - IV0004 - IV0005 - IV0010 - AC0009 - AC0010 - AC0028 - AC0029 - FL0001 - FL0006 - FL0010 - FL0011 - FL0028 - AS0015 - AS0026 - AD0015 Please refer to the error code dictionary for the details of each error code.

application/json

425

The following error codes can be returned: - GN0003 Please refer to the error code dictionary for the details of each error code.

application/json

post

POST /external/v1/primary/asset HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2904

{
  "investors": [
    {
      "data": {
        "type": "individual",
        "accreditationLevel": "qualifiedClient",
        "isInstitutional": false,
        "hasKYCPassed": false,
        "isComplianceApproved": false,
        "is5131RestrictedPerson": false,
        "name": "John Doe",
        "individualInfo": {
          "name": "John Doe",
          "dateOfBirth": "2024-09-12",
          "taxId": "123456789",
          "occupation": {
            "role": "Software Engineer",
            "companyName": "Sample Company"
          },
          "residentialAddress": {
            "addressLineOne": "8 Greenway Plaza",
            "addressLineTwo": "Suite 1515",
            "country": "US",
            "state": "Texas",
            "city": "Houston",
            "zipCode": "77046 USA"
          },
          "mailingAddress": {
            "addressLineOne": "8 Greenway Plaza",
            "addressLineTwo": "Suite 1515",
            "country": "US",
            "state": "Texas",
            "city": "Houston",
            "zipCode": "77046 USA"
          },
          "isUsPerson": true,
          "contactInfo": [
            {
              "email": "[email protected]",
              "phoneNumber": "832-426-4242"
            }
          ],
          "extraData": {
            "externalInvestorId": "123456",
            "some": "other property"
          }
        }
      },
      "documents": [
        {
          "uploadData": {
            "type": "IdentityVerification",
            "extension": "pdf",
            "name": "John Doe ID",
            "link": "https://test-storage.s3.amazonaws.com/some-id.pdf"
          },
          "extraData": {
            "someCustom": "property to be shared"
          }
        },
        {
          "fileId": "FILE3JUS03I04"
        }
      ],
      "correlationData": [
        {
          "correlationId": "INV001"
        }
      ],
      "accountAssociationData": {
        "isPrimary": true
      }
    }
  ],
  "account": {
    "correlationData": [
      {
        "correlationId": "INV001"
      }
    ],
    "data": {
      "name": "Individual Account",
      "type": "Individual",
      "relationshipType": "Brokerage",
      "bankAccount": {
        "accountNumber": "111111111",
        "accountName": "savings account",
        "bankABA": "555555555",
        "bankName": "Test Bank",
        "bankSwift": "AAAA-BB-CC-123",
        "extraData": {
          "settlementInstructions": "Please wire the amount within 72 hours",
          "some": "Other Property"
        }
      },
      "contactInfo": [
        {
          "email": "[email protected]",
          "phoneNumber": "832-426-4242",
          "type": "primary"
        },
        {
          "email": "[email protected]",
          "phoneNumber": "987-564-1234",
          "type": "tax",
          "name": "John Doe",
          "description": "Use this contact for Tax Related Information (K-1, 1099 or other tax related information)"
        }
      ],
      "custodian": {
        "data": {
          "name": "Charles Schwab"
        }
      },
      "advisors": [
        {
          "data": {
            "type": "FA",
            "name": "Chris Smith",
            "crdCode": "546321",
            "repCode": "AB98765"
          }
        }
      ],
      "authorizedSigners": [
        {
          "name": "Jane Doe",
          "primary": true,
          "extraData": {
            "externalId": "123456",
            "some": "Other Property"
          }
        }
      ],
      "beneficiaries": [
        {
          "name": "John Doe",
          "beneficialOwnership": 40,
          "individualInfo": {
            "name": "John Doe",
            "taxId": "123456789"
          }
        },
        {
          "name": "Jane Doe LLC",
          "beneficialOwnership": 60,
          "legalEntityInfo": {
            "name": "Jane Doe Private Investments and Capital Management, LLC",
            "type": "LLC",
            "taxId": "987654321"
          }
        }
      ],
      "secureExtraData": {
        "sensitive": "Data to be protected by application encryption"
      }
    }
  },
  "transactionData": {
    "securityId": "USS3JKS01I00",
    "amount": 50000,
    "signer": {
      "email": "[email protected]",
      "name": "John Doe"
    }
  },
  "documents": [
    {
      "uploadData": {
        "type": "AdditionalSubscriptionTerms",
        "extension": "pdf",
        "name": "Subscription Terms",
        "link": "https://test-storage.s3.amazonaws.com/sub-terms.pdf"
      },
      "extraData": {
        "someCustom": "property to be shared"
      }
    },
    {
      "fileId": "FILE3JUS03I04"
    }
  ],
  "bypassFileDataValidation": true,
  "dryRun": true
}

{
  "processId": "2159457f-0167-4e93-a969-9cf0db05e0bf",
  "orchestrationId": "2159457f-0167-4e93-a969-9cf0db05e0bf",
  "assetId": "US9QIMAOAS1Q",
  "fileIds": [
    "US9QIFILE1",
    "US9QIFILE2"
  ],
  "referenceData": {
    "account": {
      "accountId": "US9QIMAOAS1Q",
      "custodian": {
        "custodianId": "US9ZIMAOAS1Q"
      }
    },
    "investors": [
      {
        "investorId": "US9QIM123S1Q"
      }
    ]
  },
  "completedByAdvisor": {
    "advisorId": "OG12JUS03I04"
  },
  "dryRun": true
}