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.
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.
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".
This property contains the reference data of the account that holds the digital security.
{"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"}}}This property contains the transactional data information, i.e. which is the security being bought and the investment details
{"securityId":"USS3JKS01I00","amount":50000,"signer":{"email":"[email protected]","name":"John Doe"}}Set this to true if you want to bypass file data consistency (e.g. W9 data matching the investor/account information being provided)
trueSet 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.
falseExample: truePOST /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
}