Upvest's offers Incoming Transfers to give end users the ability to initiate the request directly on the clients’ User Interface (UI) / app.
Benefits of this API solution include:
- Enabling end users to act directly on our clients’ UI with a slick and intuitive user experience and minimum amount of information required. This includes the ability to track the status of the transfer with notifications and status updates.
- Utilising this API as an asset acquisition mechanism to increase the inflow of assets directly via our clients’ UI, while getting transfer status updates via webhook notifications.
It is important to highlight that the API for Incoming Transfers is a convenience API, as the market practice would expect the counterbroker to initiate the (outgoing) transfer on their side and to notify Upvest via allegements or pre-advice (email).
For this reason, the use of this solution will not eliminate the need for manual end-user tasks such as finalising the transfer request by sending instructions (signed PDF) to the ceding provider, where other automatic solutions are not available.
Unfulfilled incoming transfer requests will be automatically cancelled after 30 days.
Prior to submitting the request via API for an incoming transfer, the end user initiates the process in our client's UI. Once everything is validated and the form has sufficient information, the securities transfer process can be triggered and the API request is sent to Upvest. Validation on our client’s side includes:
- ISIN Validation: Client checks that ISIN is included in the enabled ISIN list.
- Account Check: Client checks that account is active.
The process of securities transfers requested via API within Upvest is similar for both incoming and outgoing, where each transfer goes through the following statuses. Any difference is specified in the following sections for each direction.
| Status | Description |
|---|---|
NEW | The transfer request has been submitted and will be validated. |
PROCESSING | The transfer has been instructed and is being processed. |
SETTLED | The transfer was executed at the custodian level. The units will be debited from the users account. Note: Partial settlement for a single ISIN (e.g., from different custodians, different timing) is not reflected in status. |
CANCELLED | The transfer was cancelled by the client, by Upvest or is rejected at the custodian level. Final state. To start the same transfer again a new one has to be created. |
Please be aware that this list of statuses may be extended in the future to accommodate additional use cases and functionalities.
{
"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"
}
}In the incoming transfers request, you must populate the fields marked as Required. Other fields remain optional.
| Field | Required/Optional | Description |
|---|---|---|
user_id | Required | User unique identifier. |
account_id | Required | Account unique identifier. |
transfer_type | Required | Type of the securities transfer. Currently, only NO_OWNER_CHANGE (no change of ownership) is supported |
direction | Required | The following values are supported: INCOMING: Transfer is incoming to the user OUTGOING: Transfer is outgoing from the user. |
settlement_reference | Required | Unique identifier of the transfer. Useful for API consumers to build special logic on their side. |
instrument_id | Required | ISIN (International Securities Identification Number) or other identity (depends on instrument_id_type) of the security to be transferred. |
instrument_id_type | Required | Type of the instrument_id. Currently, only ISIN (International Securities Identification Number) is supported. |
quantity | Required | The quantity of the instrument to move in or out. The value supported is maximum 15 digits 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. |
counterparty.bic | Required | Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) ISO 9362 |
counterparty.name | Optional | The end user’s name at the counterparty's broker. 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. |
counterparty.account_number | Optional | The account number is composed of a valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets. |
place_of_settlement | Optional | BIC code of the location where the securities are actually transferred and settled. Clearstream Frankfurt DAKVDEFFXXX or Clearstream Luxembourg CEDELULLXXX for Clearstream-internal transfers, else the BIC of the corresponding CSD. It depends on the instrument and/or counterparty. |
trade_date | Optional | The forecast date when the trade takes place. The value will change to ensure market match. If provided, usually T+1 is sufficient. Depending on the market, this means valid working days. |
settlement_date | Optional | The forecast date when the settlement takes place. The value will change to ensure market match. However, the effective settlement date might be the same date or future one. If provided, usually T+2 is sufficient or trade_date + 1. Depending on the market, this means valid working days. |
Only additional fields not present in the request are listed below.
| Field | Required/Optional | Description |
|---|---|---|
id | Required | Securities transfer request unique identifier. |
created_at | Required | Date and time when the resource was created. RFC 3339-5, ISO8601 UTC |
updated_at | Required | Date and time when the resource was updated. RFC 3339-5, ISO8601 UTC |
status | 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 |
quantity_settled | Optional | The quantity of instruments settled. This field is relevant for the future to support more complex scenarios such as partial settlements |
actual_settlement_date | Optional | The date when the transfer settled, only known in SETTLED status. Date in YYYY-MM-DD format. |
You can retrieve a list of all securities transfers (both outgoing and incoming) using:
The example below shows the request and response for incoming transfers.
{
"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": "SETTLED",
"transfer_type": "NO_OWNER_CHANGE",
"instrument_id": "US0378331005",
"instrument_id_type": "ISIN",
"quantity": "10",
"quantity_settled": "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",
"actual_settlement_date": "2024-01-24"
}