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

1. Concatenate your Corastone clientId and clientSecret as follows:

clientId:clientSecret

1. Base64 encode the resulting string.

2. 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 "}

3. Use the issued token as the bearer token in the call to functional APIs.

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

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.

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 Launch New Offering.

• For investing organizations and service providers (e.g., fund administrators), the securityId is returned after they are assigned to the security using Get Pending Assignment.

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.

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.

Setting dryRun to TRUE for the 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.

The Integration API supplies numerous document types. However, only the following types impact platform behavior:

• w8

• w8bene

• w9

These document types impact validation of investor documents.

The following table lists the descriptions of all document types listed in docType enumeration:

Questionnaires are a standard way to assess investors for participation in a fund. You can incorporate the data from a questionnaire as part of the investor details stored on the platform.

The following diagram illustrates how the questionnaires completed by an investor can be captured via the Integration API.

You can add questionnaire data using any of the following endpoints:

• Create Asset

• Remediate Asset

• Update Investor's Reference Data

Example

The following JSON excerpt captures a brief questionnaire:

"questionnaires": [ {
    "type": "Suitability",
    "questions": [
    {
       "question": {
       "questionText": "Are you an accredited investor as defined by the SEC?",
            "answerType": "Boolean"
        },
        "answers": [ {
        "booleanValue": true
        }]
        },
    {
        "question": {
           "questionText": "Which choice describes your investing style?",
           "answerType": "Choice",
              "allowedAnswerValues": [
                "Conservative", "Moderate", "Aggressive"
           ]
        },
        "answers": [ {
            "choiceValue": "Aggressive"
            }]
         }] 
    }]

Corastone provides the option of validating the content of the following investor documents against the data for the corresponding investor:

• W-9

• W-8 BEN

• W-8-BEN-E

This validation helps ensure that subscription requests proceed "in good order", with required for fields completed and matching corresponding fields in the request or an existing investor record. For example, Corastone can parse the investor's W9 to ensure that the investor's name matches the name provided in the subscription request.

To enable investor file validation for a subscription request:

• include the file information in the investor section of the request

• set bypassFileDataValidation to false

• set dryRun to false

Example Payload

The following payload from a Create Asset request provides the fileId for a W9 that has already been uploaded to the platform.

{
  "transactionData": {
    "securityId": "CDGP1D3LESYA",
    "amount": 500000,
    "signer": {
      "email": "[email protected]",
      "name": "someone"
  }},
  "investors": [{
    "documents": [
        {
          "fileId": "CDWM1BT94KD1"
        }
      ],
    "data":{
        "type":"individual",
        "accreditationLevel": "qualifiedEligibleParticipant",
        "hasKYCPassed": true,
        "isComplianceApproved": true,
        "name": "Ken Smith",
        "individualInfo": {
            "name": "Ken Smith",
            "dateOfBirth": "1957-06-10",
            "taxId": "987654523",
            "isUsPerson": true
        } }}],

    "account": {
      "data": {
        "name": "Individual Account",
        "type": "Individual",
        "relationshipType": "Advisory",
        "bankAccount": {
          "accountName": "savings account",
          "bankABA": "555525555",
          "bankName": "Test Bank"
        },
        "authorizedSigners": [
          {
          "name": "Jane Doe",
          "primary": true
        }
      ]}},
  "bypassFileDataValidation": false,
  "dryRun": false
}

When Validation Fails

File data validation is an asynchronous process initiated by the Create Asset request. Therefore, you need to check the error log for validation errors. For example, you can use the Sequencer API to retrieve the events that occurred within the relevant timeframe.

{{URL}}/external/v1/sequencer?fromDate="2025-04-10"

Here's a typical error associated with file data validation:

{
            "error": {
                "errorId": "08ce57ef-7249-4304-b623-1e44e7fd5ce3",
                "action": {
                    "id": "CEPM001",
                    "name": "Create Digital Asset",
                    "httpData": {
                        "url": "/external/v1/primary/asset",
                        "method": "POST"
                    }
                },
                "timestamp": "2025-04-10T23:04:25.338Z"
            }
        },

Get the details for the errorId to retrieve the validation errors:

{{URL}}/external/v1/error-log?errorIdsFilter=08ce57ef-7249-4304-b623-1e44e7fd5ce3

Parser errors like the following describe the validation errors:

 {
                "message": "TIN on tax document (ID: 'CDWM172F441T') does not match any investor provided as input",
                "type": "businessRuleValidations",
                "code": "PE0031",
                "context": {
                    "entities": {
                        "processIds": [
                            "45cda088-b1be-4f90-b3e0-021da14c587b"
                        ],
                        "orchestrationIds": [
                            "bd6ac60e-f0ab-482b-b987-aa28790105cf"
                        ]
                    }
                },

The issuer can specify the fee types and tiers to apply to a fund using a fee template.

A fee template defines tiers based on investment amount.

Fee templates also define the following flat fees:

• Max Frontend

• Backend

Performance fees, however, do not have tiers and are organized under common fees.

Example

The following table outlines the performance fees common for all investing orgs.

The following JSON excerpt illustrates how this fee would be defined in the payload for creating and launching the fund.

         "commonFees": {
          "performanceFees": {
            "hurdleRate": 1,
            "highWatermark": {
              "enabled": true,
              "frequency": "Quarterly"
            },
            "grossOrNet": "Net",
            "fees": [
              {
                "description": "IP period",
                "value": 1,
                "unit": "percentage",
                "frequency": "Annually"
              },
              {
                "description": "Post-IP period",
                "value": 0.5,
                "unit": "basisPoints",
                "frequency": "Semi-Annually"
              }
            ]
          }
        }       

The following table outlines the tiered and flat fees that need to be defined for Issuance A.

The following JSON excerpt illustrates how these fees would be defined in the payload for creating and launching the fund.

        "feesTemplateData": {
          "data": {
            "name": "Fee Template 1",
            "maxFrontend": 1,
            "backend": 2,
             "managementFees": [
              {
                "feesInfo": [
                  {
                    "description": "IP: annually of capital commitments",
                    "value": 2,
                    "unit": "percentage",
                    "frequency": "Annually"
                  },
                  {
                    "description": "Post-IP: annually on invested capital",
                    "value": 1.5,
                    "unit": "percentage",
                    "frequency": "Annually"
                  }
                ]
              }
            ],
            "investorServicingFees": [
              {
                "maxAmount": 4999999.99,
                "feesInfo": [
                  {
                    "value": 75,
                    "unit": "basisPoints",
                    "frequency": "One-Off"
                  }
                ]
              },
              {
                "minAmount": 5000000,
                "maxAmount": 9999999.99,
                "feesInfo": [
                  {
                    "value": 50,
                    "unit": "basisPoints",
                    "frequency": "One-Off"
                  }
                ]
              },
              {
                "minAmount": 10000000,
                "feesInfo": [
                  {
                    "value": 25,
                    "unit": "basisPoints",
                    "frequency": "One-Off"
                  }
                ]
              }
            ],
            "otherFees": [
              {
                "groupName": "Bank fees",
                "groupDetails": [
                  {
                    "maxAmount": 4999.99,
                    "feesInfo": [
                      {
                        "description": "Bank fees - tier 1 - up to $4999.99",
                        "value": 1,
                        "unit": "percentage",
                        "frequency": "Annually"
                      }
                    ]
                  },
                  {
                    "minAmount": 5000,
                    "maxAmount": 999999.99,
                    "feesInfo": [
                      {
                        "description": "Bank fees - tier 2 - $5000 - $999999.99",
                        "value": 0.5,
                        "unit": "percentage",
                        "frequency": "Annually"
                      }
                    ]
                  }
                ]
              },
              {
                "groupName": "Placement Fees",
                "groupDetails": [
                  {
                    "minAmount": 250000,
                    "maxAmount": 999999.99,
                    "feesInfo": [
                      {
                        "description": "Client Pays",
                        "value": 1.25,
                        "unit": "percentage",
                        "frequency": "One-Off"
                      },
                      {
                        "description": "GP Pays",
                        "value": 0.75,
                        "unit": "percentage",
                        "frequency": "One-Off"
                      },
                      {
                        "description": "Total FA Comp",
                        "value": 2,
                        "unit": "percentage",
                        "frequency": "One-Off"
                      }
                    ]
                  },
                  {
                    "minAmount": 1000000,
                    "feesInfo": [
                      {
                        "description": "Client Pays",
                        "value": 0.25,
                        "unit": "percentage",
                        "frequency": "One-Off"
                      },
                      {
                        "description": "GP Pays",
                        "value": 0.75,
                        "unit": "percentage",
                        "frequency": "One-Off"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        },

Expanded Data Model

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.

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