Request:

mutation {
  bulkDeposit (
    input : {
      securityId: ""
      idempotencyId: ""
      deposit: [
        {
          idempotencyId: ""
          depositAddressId: ""
          investorId: ""
          externalInvestorId: ""
          date: ""
          holdings: [
            {
              id: ""
              amount: ""
            }
          ]
          signature: {
            status: ""
            signature: ""
            date: ""
          }
          investorInformation: {
            name: ""
            taxId: ""
            email: ""
            address: [
              {
                lineOne: ""
                lineTwo: ""
                lineThree: ""
                lineFour: ""
                city: ""
                province: ""
                postalCode: ""
                country: ""
              }
            ]
            data: {
              field1: ""
              field2: ""
            }
            parties: [
              {
                firstName: ""
                lastName: ""
                taxId: ""
                email: ""
                address: [
                  {
                    lineOne: ""
                    lineTwo: ""
                    lineThree: ""
                    lineFour: ""
                    city: ""
                    province: ""
                    postalCode: ""
                    country: ""
                  }
                ]
              }
            ]
          }
          tags: [
            {
              id: ""
              data: {
                field1: ""
                field2: ""
              }
            }
          ]
          fee: {
            currency: ""
            amount: ""
          }
        }
      ]
    }
  ) {
    id
    accountId
    securityId
    requestId
    type
    status
    createdOn
    executedOn
    requestByRequestId {
      data
    }
  }
}

The example above shows the full extent of the bulkDeposit mutation, through which you submit one or more deposit requests for deposit into a custodial (omnibus) account for a specific security. This is required in use cases where a custodian is engaged to hold investor shares typically for secondary liquidity where investors intend on trading their shares of an issuer’s security listed on an ATS or other regulated exchange. The deposit field is an array which contains one more deposit requests, each of which provides the required detail of the respective deposit. Each deposit must go through a review process, and once approved, the investor’s shares are transferred to the custodian’s omnibus account on the issuer’s cap table.

Note: Not all fields in the mutation are required. Please refer to the Documentation Explorer in GraphiQL (described in the Getting Going section of the Introduction) for a detailed description of the mutation, including field types, required fields, etc.

Note: Vertalo must separately configure the omnibus account for the custodian (per security) before deposit requests can be submitted. This determines the value of the depositAddressId which will be supplied to you for use in the mutation. Vertalo support will coordinate with you to complete this process.

Request:

mutation {
  bulkDeposit (
    input : {
      securityId: "ea103313-ec6d-421c-b022-b9f9357c727f"
      idempotencyId: "7c2a6dfb-4f53-4c96-9ee7-dacf16efaf38"
      deposit: [
        {
          idempotencyId: "5ae24eac-ebf7-45ce-ae0b-db7871a59298"
          depositAddressId: "891756e5-d17e-4628-8785-d7d98e1200c8"
          investorId: "0f8c0aca-22f6-4179-bc6a-d3f6ba0d2e58"
          externalInvestorId: "b7b4d0f1-dce5-4da4-910b-b87bad3bbf6b"
          date: "2022-07-15T21:52:32.440Z"
          holdings: [
            {
              id: "fb1e6f55-7d2e-4ba1-8a92-fb0844fd0d59"
              amount: "10000"
            }
          ]
          signature: {
            status: "true"
            signature: "Neil Armstrong"
            date: "2022-07-21T21:52:32.430Z"
          }
          fee: {
            currency: "USD"
            amount: "1.00"
          }
        }
      ]
    }
  ) {
    id
    accountId
    securityId
    requestId
    type
    status
    createdOn
    executedOn
    requestByRequestId {
      data
    }
  }
}

In this (concrete) example, the mutation submits a single deposit request for a single investor holding into a custodial (omnibus) account.

Response

The response from the bulkDeposit mutation is a JSON object which contains an array of the deposit requests submitted through the mutation. The array is ordered based on the ordering of the deposit requests. Each object in the array corresponds to a single deposit and may contain any or all of the following fields (depending on which ones you include in the mutation return payload):

• id (uuid)
• accountId (uuid)
• securityId (uuid)
• requestId (uuid)
• type (string)
• status (string)
• webhookId (uuid)
• data (JSON)
• createdOn (datetime)
• executedOn (datetime)

You may also include a requestByRequestId field in the mutation response; this allows you to inspect a data field which contains a JSON blob that corresponds to the original deposit request you submitted.

Idempotency

An idempotency ID is required for the mutation as a whole, as well as for each deposit object in the mutation. These IDs are returned to you using the requestByRequestId field mentioned above.

Webhook

Vertalo will configure a webhook which will issue a callback to an endpoint you provide. The callback will be issued for each deposit contained in the bulkDeposit mutation, once the deposit has been reviewed and a disposition assigned. The format of the callback is:

{
  "id": "<UUID of deposit request>",
  "status": "complete | failed"
}

The id field contained in the callback corresponds to an id field in the response returned by the mutation (see above).

Authorization

In order to verify that the callback is coming from Vertalo, we will configure a shared secret to be included in a JWT in the Authorization header of the callback. Vertalo support will coordinate with you to complete this process.

Testing

For testing purposes, you can make use of a feature that let’s you configure a deposit request to be automatically approved or rejected. This will result in a callback to the endpoint we have configured as your webhook for deposit requests. This feature is ONLY available in the Vertalo sandbox environment. To implement this feature you must included the tags field in your deposit request as follows:

tags: [
  {    
    id: "<your UUID>"
    data: {
        _autocomplete_to_status: "complete"
    }
 }
]

-or-

tags: [
  {    
    id: "<your UUID>"
    data: {
        _autocomplete_to_status: "failed"
    }
  }
]