Skip to content
Optimal Outcomes
/
OpenAPI Specs
/
/transferbatch-v1

Transfer Position External API (1.0.0)

Use API credentials to view and manage instruments.

Download OpenAPI description
optimal.transferposition.v1.openapi.json
optimal.transferposition.v1.openapi.yaml
Languages
Servers
https://optimalapi-ext.apx.com/transfer/v1/
https://optimalapi-uat-ext.apx.com/transfer/v1/

transferbatch-v1

Initiate a transfer request (between subaccounts or another account holder), view or act upon pending transfers, as well as view historical transfer details.

Operations

Initiate counterparty transfer

Request

Initiate transfer will propose the transaction to the counterparty, after which the counterparty will be prompted to act on the proposal.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Bodyapplication/jsonrequired

Bulk Transfer Request payload

onBehalfOfSrcAcctIdstring

If permitted, allows the caller to initiate transfer batches on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

requestsArray of objects(InteraccountTransferRequest)

Collection of Transfer requests

curl -i -X POST \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/transfer \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onBehalfOfSrcAcctId": "string",
    "requests": [
      {
        "transfereeSrcAcctId": "b5d8d6b3-bcaf-11ef-ae69-b61606fd520c",
        "holdingCriteria": [
          {
            "holdingIdentifier": "476099",
            "quantity": 3
          }
        ],
        "correlationId": "string",
        "requestConfirmation": true,
        "toSubaccountIdentifier": "string",
        "totalPrice": 0,
        "currencyCode": "string",
        "notes": "string"
      }
    ]
  }'

Responses

success

Bodyapplication/json
responsesArray of objects(InteraccountTransferResponse)

Bulk Transfer Response

Response
application/json
{
  "responses": [
    { … }
  ]
}

Act on a proposed transfer

Request

Actions include accept, reject or withdrawal of a proposed transfer, using the transfer batch identifier.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Bodyapplication/jsonrequired

Populated ActionTransferBatches payload

onBehalfOfSrcAcctIdstring

If permitted, allows the caller to perform actions on open transfer batches on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

actionstring

Specifies code of action to take; same action for all transfer batches included in "items".

Enum"CONFIRM""WITHDRAW""REJECT"
Example: "WITHDRAW"
itemsArray of objects(ActionTransferBatchItem)

List of transfer batch identifiers

curl -i -X POST \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/transferBatch/open/action \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onBehalfOfSrcAcctId": "string",
    "action": "WITHDRAW",
    "items": [
      {
        "batchIdentifier": "7644439A-A56B-45E5-AFE6-94E149CF014E"
      }
    ]
  }'

Responses

success

Retrieve transfer request details

Request

View the details behind a transfer request, using the transfer batch identifier.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Bodyapplication/jsonrequired

Populated TransferBatchRetrieveByIdentifierRequest

onBehalfOfSrcAcctIdstring

If permitted, allows the caller to initiate transfer batches on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

transferBatchIdentifiersArray of stringsunique

System-assigned identifiers associated with the transfer batches to be retrieved.

curl -i -X POST \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/transferBatch/byIdentifier \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onBehalfOfSrcAcctId": "string",
    "transferBatchIdentifiers": [
      "string"
    ]
  }'

Responses

success

Bodyapplication/json
transferBatchesArray of objects(TransferBatch)

Collection of retrieved Transfer Batches

Response
application/json
{
  "transferBatches": [
    { … }
  ]
}

Transfer holdings between subaccounts

Request

Transfers holdings between active subaccounts, within the same account.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Bodyapplication/jsonrequired

Bulk Subaccount Transfer request

onBehalfOfSrcAcctIdstring

If permitted, allows the caller to initiate subaccount transfers on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

requestsArray of objects(SubaccountTransferRequest)

Collection of Subaccount transfer requests

curl -i -X POST \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/transfer/subaccount \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onBehalfOfSrcAcctId": "string",
    "requests": [
      {
        "subaccountIdentifier": "string",
        "holdingCriteria": [
          {
            "holdingIdentifier": "476099",
            "quantity": 3
          }
        ],
        "correlationId": "string"
      }
    ]
  }'

Responses

success

Bodyapplication/json
responsesArray of objects(SubaccountTransferResponse)

Bulk Subaccount Transfer response

Response
application/json
{
  "responses": [
    { … }
  ]
}

Retrieve pending transfer requests

Request

Retrieve list of currently pending transfers.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Query
directionstring

Specify whether you want only "in"bound or "out"bound pending transfers. If omitted, both types will be returned.

Enum"in""out"
Example: direction=direction="in"
includeHoldingsboolean

Include transfer related holdings details

Example: includeHoldings=?includeHoldings=true
onBehalfOfSrcAcctIdstring

If permitted, allows the caller to retrieve open transfer batches on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

$skipinteger(int32)

Number of records to skip

$topinteger(int32)

Maximum number of records to return

$filterstring

OData-like filter expression

$applystring

OData-like apply expression with groupby and aggregate only

$orderbystring

Comma-separated list of columns for sorting

$countboolean

Whether to include the count of records with the result

curl -i -X GET \
  'https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/transferBatch/open?direction=direction%3D%22in%22&includeHoldings=%3FincludeHoldings%3Dtrue&onBehalfOfSrcAcctId=string&%24skip=0&%24top=0&%24filter=string&%24apply=string&%24orderby=string&%24count=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

transfer batches retrieved

Bodyapplication/json
inboundArray of objects(TransferBatch)

Inbound transfer batches that are visible-to-the-caller; as the transfer recipient, the API user can usually accept or reject.

outboundArray of objects(TransferBatch)

Outbound transfer batches that are visible-to-the-caller; as the transfer initiator, the API user can usually withdraw.

Response
application/json
{
  "inbound": [
    { … }
  ],
  "outbound": [
    { … }
  ]
}

retirementbatch-v1

View or submit a retirement request, or redemption claim, on instrument(s).

Operations

ledger-v1

View an Account's current and historical instrument details

Operations

subaccount-v1

View or create subaccounts. Use subaccounts to organize your account’s instruments. All accounts have a "Default" subaccount, where all new issuances and incoming transfers will be deposited. Subaccounts may also be used to delegate instrument management to an authorized third party.

Operations