API status

Securities Transfers

All Securities Transfers related paths.

get

List securities transfers

List securities transfers

directionstring

required

Filter the list by transfer direction.

Enum
  • INCOMING
  • OUTGOING
sortstring

Sort the result by created_at, updated_at.

Default
"created_at"
Enum
  • created_at
  • updated_at
orderstring

Sort order of the result list if the sort parameter is specified. Use ASC for ascending or DESC for descending sort order.

Default
"ASC"
Enum
  • ASC
  • DESC
offsetint

Use the offset argument to specify where in the list of results to start when returning items for a particular query.

Format
int32
Min
0
limitint

Use the limit argument to specify the maximum number of items returned.

Format
int32
Default
100
Min
0
Max
1000
user_idstring

User unique identifier.

Format
uuid
account_idstring

Account unique identifier.

Format
uuid
account_group_idstring

Account group unique identifier.

Format
uuid
statusstring

Status of the securities transfer

  • NEW - Securities transfer is created but not started processing.
  • PROCESSING - Securities transfer is in processing.
  • SETTLED - Securities transfer was successfully settled.
  • CANCELLED - Securities transfer was cancelled.
Enum
  • NEW
  • PROCESSING
  • CANCELLED
  • SETTLED

Responses

Response examples

Securities Transfers list

{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 2,
    "total_count": 2,
    "sort": "created_at",
    "order": "ASC"
  },
  "data": [
    {
      "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
      "created_at": "2024-01-22T14:10:00.00Z",
      "updated_at": "2024-01-22T14:12:34.56Z",
      "direction": "INCOMING",
      "status": "NEW",
      "transfer_type": "NO_OWNER_CHANGE",
      "instrument_id": "US0378331005",
      "instrument_id_type": "ISIN",
      "quantity": "10",
      "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
      "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
      "settlement_reference": "b82dc5985558fdr2",
      "counterparty": {
        "bic": "DUMBZZ33XXX",
        "account_number": "1234567891",
        "name": "Max Mustermann"
      },
      "place_of_settlement": "DAKVDEFFXXX",
      "trade_date": "2024-01-22",
      "settlement_date": "2024-01-23"
    },
    {
      "id": "64464124-18a2-4886-bc9f-c1b41fa8e4df",
      "created_at": "2025-01-22T14:10:00.00Z",
      "updated_at": "2025-01-22T14:12:34.56Z",
      "direction": "INCOMING",
      "status": "SETTLED",
      "transfer_type": "NO_OWNER_CHANGE",
      "instrument_id": "US88160R1014",
      "instrument_id_type": "ISIN",
      "quantity": "5",
      "quantity_settled": "5",
      "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
      "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
      "settlement_reference": "b82dc5985558fdr2",
      "counterparty": {
        "bic": "DUMBZZ33XXX",
        "account_number": "1234567891",
        "name": "Max Mustermann"
      },
      "place_of_settlement": "CEDELULLXXX",
      "trade_date": "2024-01-22",
      "settlement_date": "2024-01-23",
      "actual_settlement_date": "2024-01-24"
    }
  ]
}
post

Create securities transfer

Create securities transfer

directionstring

required

Direction of the securities transfer

  • INCOMING - Securities transfer is incoming to the user.
  • OUTGOING - Securities transfer is outgoing from the user.
Enum
  • INCOMING
  • OUTGOING
instrument_idstring

required

ISIN or other identity (depends on instrument_id_type) of the security to be transferred.

instrument_id_typestring

required

Type of the instrument_id

  • ISIN - International Securities Identification Number
Enum
  • ISIN
quantitystring

required

The quantity of instrument to move in or out. The value supported is maximum 15 digits including decimal place. Note: For INCOMING the end user ensures that they don't sell their instruments on the counter-broker to enable smooth transfer of their instruments on Upvest platform.

Pattern
^[0-9]{0,63}(\.[0-9]{1,27})?$
transfer_typestring

required

Type of the securities transfer

  • NO_OWNER_CHANGE - No change of ownership.
Enum
  • NO_OWNER_CHANGE
user_idstring

required

User unique identifier.

Format
uuid
account_idstring

required

Account unique identifier.

Format
uuid
place_of_settlementstring

Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) ISO 9362.

Pattern
^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
settlement_referencestring

required

Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest! TIP: For non-live environment if you prefix the reference with AUTO your transfer gets through all lifecycle states.

Pattern
^[0-9A-Za-z+?/\-:()\.,' ]*$
counterpartyobject

required

bicstring

required

Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) ISO 9362.

Pattern
^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
account_numberstring

The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.

Pattern
^[0-9A-Za-z+?/\-:()\.,' ]{0,28}$
namestring

The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.

Pattern
^[0-9A-Za-z+?/\-:()\.,' ]{0,140}$
trade_datestring

Optional forecast date when the trade takes place. If provided, usually T+1 is sufficient. Depending on the market this means valid working days. Date in YYYY-MM-DD format.

Format
date
settlement_datestring

Optional forecast date when the settlement takes place. If provided, usually T+2 is sufficient or trade_date + 1. Depending on the market this means valid working days. Date in YYYY-MM-DD format.

Format
date

Responses

Request examples

{
  "direction": "INCOMING",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "quantity": "10",
  "transfer_type": "NO_OWNER_CHANGE",
  "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
  "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
  "settlement_reference": "b82dc5985558fdr2",
  "counterparty": {
    "bic": "DUMBZZ33XXX",
    "account_number": "1234567891",
    "name": "Max Mustermann"
  }
}

Response examples

Securities Transfer created

{
  "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
  "created_at": "2024-01-22T14:10:00.00Z",
  "updated_at": "2024-01-22T14:12:34.56Z",
  "direction": "INCOMING",
  "status": "NEW",
  "transfer_type": "NO_OWNER_CHANGE",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "quantity": "10",
  "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
  "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
  "settlement_reference": "b82dc5985558fdr2",
  "counterparty": {
    "bic": "DUMBZZ33XXX",
    "account_number": "1234567891",
    "name": "Max Mustermann"
  },
  "place_of_settlement": "DAKVDEFFXXX",
  "trade_date": "2024-01-22",
  "settlement_date": "2024-01-23"
}
webhook

Securities Transfers events

idstring

required

Event unique identifier

Format
uuid
created_atstring

required

Date and time when the event was created. RFC 3339-5, ISO8601 UTC

Format
date-time
typestring

required

Event type

Enum
  • SECURITIES_TRANSFER.NEW
  • SECURITIES_TRANSFER.PROCESSING
  • SECURITIES_TRANSFER.SETTLED
  • SECURITIES_TRANSFER.CANCELLED
  • SECURITIES_TRANSFER.DATA_CHANGED
objectobject

required

idstring

required

Securities transfer request unique identifier.

Format
uuid
created_atstring

required

Date and time when the resource was created. RFC 3339-5, ISO8601 UTC

Format
date-time
updated_atstring

required

Date and time when the resource was last updated. RFC 3339-5, ISO8601 UTC

Format
date-time
directionstring

required

Direction of the securities transfer

  • INCOMING - Securities transfer is incoming to the user.
  • OUTGOING - Securities transfer is outgoing from the user.
Enum
  • INCOMING
  • OUTGOING
statusstring

required

Status of the securities transfer

  • NEW - Securities transfer is created but not started processing.
  • PROCESSING - Securities transfer is in processing.
  • SETTLED - Securities transfer was successfully settled.
  • CANCELLED - Securities transfer was cancelled.
Enum
  • NEW
  • PROCESSING
  • SETTLED
  • CANCELLED
transfer_typestring

required

Type of the securities transfer

  • NO_OWNER_CHANGE - No change of ownership.
Enum
  • NO_OWNER_CHANGE
instrument_idstring

required

ISIN or other identity (depends on instrument_id_type) of the security to be transferred.

instrument_id_typestring

required

Type of the instrument_id

  • ISIN - International Securities Identification Number
Enum
  • ISIN
quantitystring

required

The quantity of instrument to move in or out.

Pattern
^[0-9]{0,63}(\.[0-9]{1,27})?$
quantity_settledstring

The quantity of instruments settled.

Pattern
^[0-9]{0,63}(\.[0-9]{1,27})?$
user_idstring

required

User unique identifier.

Format
uuid
account_idstring

required

Account unique identifier.

Format
uuid
place_of_settlementstring

Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) ISO 9362.

Pattern
^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
settlement_referencestring

required

Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!

Pattern
^[0-9A-Za-z+?/\-:()\.,' ]*$
counterpartyobject

required

trade_datestring

required

The forecast date when the trade takes place. Date in YYYY-MM-DD format.

Format
date
settlement_datestring

required

The forecast date when the settlement takes place. Date in YYYY-MM-DD format.

Format
date
actual_settlement_datestring

The date when the transfer settled, only known in SETTLED status. Date in YYYY-MM-DD format.

Format
date
webhook_idstring

required

Webhook unique identifier.

Format
uuid

Responses

Request examples

{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "SECURITIES_TRANSFER.NEW",
  "object": {
    "id": "9637e68f-7065-4131-a072-6d57044ebd8c",
    "created_at": "2024-01-22T14:10:00.00Z",
    "updated_at": "2024-01-22T14:12:34.56Z",
    "direction": "INCOMING",
    "status": "NEW",
    "transfer_type": "NO_OWNER_CHANGE",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "quantity": "10",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": {
      "bic": "DUMBZZ33XXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    },
    "place_of_settlement": "DAKVDEFFXXX",
    "trade_date": "2024-01-22",
    "settlement_date": "2024-01-23"
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}

Response examples

Request has been processed successfully.

Empty response

Was this page helpful?