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

/external/v1/primary/asset

Synopsis

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

Required scopes

This endpoint requires the following scopes:

• : createSubscription

Authorizations

oauth2

OAuth2clientCredentialsRequired

Token URL:

Body

application/json

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 - IV0022 - IV0017 - IV0016 - IV0023 - IV0035 - IV0032 - IV0036 - IV0037 - IV0040 - IV0041 - IV0017 - IV0042 - AC0006 - AC0007 - AC0013 - AC0014 - AC0016 - AC0049 - AC0044 - AC0027 - AC0050 - AC0063 - AC0064 - 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: - IS0119 - IS0012 - IS0013 - IS0026 - IS0027 - IS0028 - IS0029 - IS0030 - IS0034 - IS0117 - AS0017 - IV0003 - IV0004 - IV0005 - IV0010 - AC0009 - AC0010 - AC0029 - FL0001 - FL0006 - FL0010 - FL0011 - AS0015 - AS0026 - AS0045 - AD0015 - FL0028 - IV0024 - AC0037 - CT0003 - AD0003 - PO0001 - FL0012 - AS0026 - IV0027 - AC0039 - CT0007 - AD0006 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

/external/v1/primary/asset

HTTPcURLJavaScriptPython

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

{
  "investors": [
    {
      "data": {
        "type": "individual",
        "accreditationLevel": "qualifiedClient",
        "isInstitutional": false,
        "hasKYCPassed": false,
        "isComplianceApproved": false,
        "is5131RestrictedPerson": false,
        "isNominee": true,
        "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,
          "isNominee": true,
          "isKeyController": true,
          "isExecutor": true,
          "isAdministrator": true,
          "isSettlor": true,
          "extraData": {
            "externalId": "123456",
            "some": "Other Property"
          }
        }
      ],
      "beneficiaries": [
        {
          "name": "John Doe",
          "beneficialOwnership": 40,
          "isNominee": true,
          "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"
    }
  ],
  "externalEntityState": {
    "status": "PENDING",
    "extraData": {
      "some": "custom property"
    }
  },
  "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,
  "positionId": "US9QIMAOAS1Q"
}

Important Notes

• See Blockchain Transaction Tracking for information on using orchestrationId and processId.

• Use the dryRun option to check the submission for completeness and correctness without persisting the information.