Skip to content
/
Retrieve account transfer

Upvest Investment API (1.79.0)

Upvest Investment API.

Download OpenAPI description
Upvest-Investment-API.v1.json
Upvest-Investment-API.v1.yaml
Overview
URL
https://docs.upvest.co
Upvest API Support
api@upvest.co
License
Apache 2.0
Languages
Servers
Sandbox environment
https://sandbox.upvest.co/
Live environment
https://api.upvest.co/

Access Tokens

All authentication related paths.

Operations

Users

All user related paths.

OperationsWebhooks

User Identifiers

All user identifiers related paths.

Operations

User Checks

All user checks related paths.

OperationsWebhooks

Accounts

All accounts related paths

OperationsWebhooks

Account Groups

All account groups related paths

OperationsWebhooks

Tax Residencies

All tax residencies related paths.

Operations

Corporate Actions

All Corporate Action related paths.

Webhooks

Tax Wrappers

All tax wrappers related paths

OperationsWebhooks

Tax Exemptions

All tax exemptions related paths

OperationsWebhooks

Tax Collections

All tax collections related paths

Webhooks

Instruments

All instrument related paths.

OperationsWebhooks

Price Data

All price data related paths.

Operations

Orders

All order related paths.

OperationsWebhooks

Portfolios

All portfolios related paths.

Operations

Portfolios Rebalancing

All portfolios rebalancing related paths.

OperationsWebhooks

Savings Plans

All savings plans related paths.

OperationsWebhooks

Liquidations

All accounts liquidations related paths.

OperationsWebhooks

Direct Debits

All direct debits related paths

OperationsWebhooks

Top-ups

All top-ups related paths

OperationsWebhooks

Withdrawals

All withdrawals related paths

OperationsWebhooks

Reference Accounts

All reference account related paths

Operations

Mandates

All direct debit mandates related paths

Operations

Virtual Bank Accounts

All virtual bank accounts related paths

OperationsWebhooks

Credit Fundings

All credit fundings related paths

OperationsWebhooks

Cash Balances

All cash balance related paths

OperationsWebhooks

Positions

All positions related paths.

OperationsWebhooks

Valuations

All valuations related paths.

OperationsWebhooks

Returns

All accounts returns related paths.

OperationsWebhooks

Virtual Cash Balances

All virtual cash balances related paths

OperationsWebhooks

Fees

All fees related paths.

OperationsWebhooks

Fees Configurations

All fees configurations related paths.

Operations

Transaction Fees Models

All transaction fees models related paths.

Reports

All reports related paths.

OperationsWebhooks

Treasury Reports

All treasury reports related paths.

Webhooks

Transactions

All transactions related paths.

OperationsWebhooks

Files

All files API related paths.

Operations

Account Transfers

All Accounts Transfers related paths.

OperationsWebhooks

Create account transfer

Request

Create account transfer

Security
oauth-client-credentials
Headers
upvest-client-idstring(uuid)required

Tenant Client ID

Example: ebabcf4d-61c3-4942-875c-e265a7c2d062
authorizationstring^Bearer [a-zA-Z0-9\-\._~+/]*=*required

Bearer (access) token from the OAuth flow with correct scopes. https://datatracker.ietf.org/doc/html/rfc6750

Example: Bearer c2VjcmV0Cg==
signaturestringrequired

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

signature-inputstringrequired

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

idempotency-keystring(uuid)^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-f...required

A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed. https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

Example: ccb07f42-4104-44ad-8e1f-c660bb7b269c
upvest-api-versionstring

Upvest API version (Note: Do not include quotation marks)

Default 1
Value"1"
Example: 1
Bodyapplication/json
directionstringrequired

Direction of the securities transfer

  • INCOMING - Securities transfer is incoming to the user.
  • OUTGOING - Securities transfer is outgoing from the user.
Enum"INCOMING""OUTGOING"
user_idstring(uuid)required

User unique identifier.

account_idstring(uuid)required

Account unique identifier.

transfer_typestringrequired

Type of the securities transfer

  • NO_OWNER_CHANGE - No change of ownership.
Value"NO_OWNER_CHANGE"
settlement_referencestring^[0-9A-Za-z+?/\-:()\.,' ]*$required

Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: This reference will be set and be common to all securities transfers

instrumentsArray of objectsrequired

For INCOMING at least one instrument should be defined. For OUTGOING an empty list means full transfer of full units of the account.

idstringrequired

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

id_typestringrequired

Type of the instrument_id

  • ISIN - International Securities Identification Number
Value"ISIN"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$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.

counterpartyobjectrequired
bicstring^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$required

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

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

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.

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

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.

trade_datestring(date)

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. NOTE: Each individual transfer can differ based on market needs.

settlement_datestring(date)

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. *NOTE: Each individual transfer can differ based on market needs.

curl -i -X POST \
  https://sandbox.upvest.co/account_transfers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'authorization: Bearer c2VjcmV0Cg==' \
  -H 'idempotency-key: ccb07f42-4104-44ad-8e1f-c660bb7b269c' \
  -H 'signature: string' \
  -H 'signature-input: string' \
  -H 'upvest-api-version: 1' \
  -H 'upvest-client-id: ebabcf4d-61c3-4942-875c-e265a7c2d062' \
  -d '{
    "direction": "INCOMING",
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "transfer_type": "NO_OWNER_CHANGE",
    "settlement_reference": "b82dc5985558fdr2",
    "instruments": [
      {
        "id": "US0378331005",
        "id_type": "ISIN",
        "quantity": "10"
      },
      {
        "id": "US64110L1061",
        "id_type": "ISIN",
        "quantity": "5"
      }
    ],
    "counterparty": {
      "bic": "ABCDDEFFXXX",
      "account_number": "1234567891",
      "name": "Max Mustermann"
    }
  }'

Responses

Account Transfer created

Headers
upvest-request-idstring(uuid)required
Example: "169ae4c7-ebd7-4041-94da-25369653eba7"
Bodyapplication/json
idstring(uuid)required

Account transfer request unique identifier.

created_atstring(date-time)required

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

updated_atstring(date-time)required

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

directionstringrequired

Direction of the account transfer

  • INCOMING - account transfer is incoming to the user.
  • OUTGOING - account transfer is outgoing from the user.
Enum"INCOMING""OUTGOING"
statusstringrequired

Status of the account transfer

  • NEW - account transfer is created but not started processing.
  • PROCESSING - account transfer is in processing.
  • SETTLED - account transfer was successfully settled.
  • PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.
  • CANCELLED - account transfer was cancelled.
Enum"NEW""PROCESSING""SETTLED""PARTIALLY_SETTLED""CANCELLED"
transfer_typestringrequired

Type of the account transfer

  • NO_OWNER_CHANGE - No change of ownership.
Value"NO_OWNER_CHANGE"
instrumentsArray of objectsrequired

List of instruments positions.

idstringrequired

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

id_typestringrequired

Type of the instrument_id

  • ISIN - International Securities Identification Number
Value"ISIN"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required

The quantity of instrument to move in or out.

statusstringrequired

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_idstring(uuid)required

Securities transfer request unique identifier.

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

The quantity of instruments settled.

user_idstring(uuid)required

User unique identifier.

account_idstring(uuid)required

Account unique identifier.

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

Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: This reference will be set and be common to all securities transfers.

counterpartyobjectrequired
bicstring^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$required

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

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

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.

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

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.

trade_datestring(date)

The forecast date when the trade takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

settlement_datestring(date)

The forecast date when the settlement takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

Response
application/json
{
  "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645",
  "created_at": "2025-01-22T14:10:00.00Z",
  "updated_at": "2025-01-22T14:12:34.56Z",
  "direction": "INCOMING",
  "status": "NEW",
  "transfer_type": "NO_OWNER_CHANGE",
  "instruments": [
    { … },
    { … }
  ],
  "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
  "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
  "settlement_reference": "b82dc5985558fdr2",
  "counterparty": {
    "bic": "ABCDDEFFXXX",
    "account_number": "1234567891",
    "name": "Max Mustermann"
  }
}

Retrieve account transfer

Request

Retrieve account transfer

Security
oauth-client-credentials
Path
account_transfer_idstring(uuid)required

Account transfer request unique identifier.

Headers
upvest-client-idstring(uuid)required

Tenant Client ID

Example: ebabcf4d-61c3-4942-875c-e265a7c2d062
authorizationstring^Bearer [a-zA-Z0-9\-\._~+/]*=*required

Bearer (access) token from the OAuth flow with correct scopes. https://datatracker.ietf.org/doc/html/rfc6750

Example: Bearer c2VjcmV0Cg==
signaturestringrequired

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

signature-inputstringrequired

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

upvest-api-versionstring

Upvest API version (Note: Do not include quotation marks)

Default 1
Value"1"
Example: 1
curl -i -X GET \
  'https://sandbox.upvest.co/account_transfers/{account_transfer_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'authorization: Bearer c2VjcmV0Cg==' \
  -H 'signature: string' \
  -H 'signature-input: string' \
  -H 'upvest-api-version: 1' \
  -H 'upvest-client-id: ebabcf4d-61c3-4942-875c-e265a7c2d062'

Responses

Account Transfer object

Headers
upvest-request-idstring(uuid)required
Example: "169ae4c7-ebd7-4041-94da-25369653eba7"
Bodyapplication/json
idstring(uuid)required

Account transfer request unique identifier.

created_atstring(date-time)required

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

updated_atstring(date-time)required

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

directionstringrequired

Direction of the account transfer

  • INCOMING - account transfer is incoming to the user.
  • OUTGOING - account transfer is outgoing from the user.
Enum"INCOMING""OUTGOING"
statusstringrequired

Status of the account transfer

  • NEW - account transfer is created but not started processing.
  • PROCESSING - account transfer is in processing.
  • SETTLED - account transfer was successfully settled.
  • PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.
  • CANCELLED - account transfer was cancelled.
Enum"NEW""PROCESSING""SETTLED""PARTIALLY_SETTLED""CANCELLED"
transfer_typestringrequired

Type of the account transfer

  • NO_OWNER_CHANGE - No change of ownership.
Value"NO_OWNER_CHANGE"
instrumentsArray of objectsrequired

List of instruments positions.

idstringrequired

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

id_typestringrequired

Type of the instrument_id

  • ISIN - International Securities Identification Number
Value"ISIN"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required

The quantity of instrument to move in or out.

statusstringrequired

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_idstring(uuid)required

Securities transfer request unique identifier.

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

The quantity of instruments settled.

user_idstring(uuid)required

User unique identifier.

account_idstring(uuid)required

Account unique identifier.

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

Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: This reference will be set and be common to all securities transfers.

counterpartyobjectrequired
bicstring^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$required

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

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

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.

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

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.

trade_datestring(date)

The forecast date when the trade takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

settlement_datestring(date)

The forecast date when the settlement takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

Response
application/json
{
  "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645",
  "created_at": "2025-01-22T14:10:00.00Z",
  "updated_at": "2025-01-22T14:12:34.56Z",
  "direction": "INCOMING",
  "status": "NEW",
  "transfer_type": "NO_OWNER_CHANGE",
  "instruments": [
    { … },
    { … }
  ],
  "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
  "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
  "settlement_reference": "b82dc5985558fdr2",
  "counterparty": {
    "bic": "ABCDDEFFXXX",
    "account_number": "1234567891",
    "name": "Max Mustermann"
  }
}

Account Transfer eventsWebhook

Request

Account Transfer events

Bodyapplication/json
idstring(uuid)required

Event unique identifier

created_atstring(date-time)required

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

typestringrequired

Event type

Enum"ACCOUNT_TRANSFER.NEW""ACCOUNT_TRANSFER.PROCESSING""ACCOUNT_TRANSFER.SETTLED""ACCOUNT_TRANSFER.PARTIALLY_SETTLED""ACCOUNT_TRANSFER.CANCELLED"
objectobjectrequired
idstring(uuid)required

Account transfer request unique identifier.

created_atstring(date-time)required

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

updated_atstring(date-time)required

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

directionstringrequired

Direction of the account transfer

  • INCOMING - account transfer is incoming to the user.
  • OUTGOING - account transfer is outgoing from the user.
Enum"INCOMING""OUTGOING"
statusstringrequired

Status of the account transfer

  • NEW - account transfer is created but not started processing.
  • PROCESSING - account transfer is in processing.
  • SETTLED - account transfer was successfully settled.
  • PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.
  • CANCELLED - account transfer was cancelled.
Enum"NEW""PROCESSING""SETTLED""PARTIALLY_SETTLED""CANCELLED"
transfer_typestringrequired

Type of the account transfer

  • NO_OWNER_CHANGE - No change of ownership.
Value"NO_OWNER_CHANGE"
instrumentsArray of objectsrequired

List of instruments positions.

idstringrequired

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

id_typestringrequired

Type of the instrument_id

  • ISIN - International Securities Identification Number
Value"ISIN"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required

The quantity of instrument to move in or out.

statusstringrequired

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_idstring(uuid)required

Securities transfer request unique identifier.

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

The quantity of instruments settled.

user_idstring(uuid)required

User unique identifier.

account_idstring(uuid)required

Account unique identifier.

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

Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it. NOTE: This reference will be set and be common to all securities transfers.

counterpartyobjectrequired
bicstring^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$required

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

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

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.

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

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.

trade_datestring(date)

The forecast date when the trade takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

settlement_datestring(date)

The forecast date when the settlement takes place. Date in YYYY-MM-DD format. NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.

webhook_idstring(uuid)required

Webhook unique identifier.

application/json
{
  "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353",
  "created_at": "2024-01-22T14:10:00.00Z",
  "type": "ACCOUNT_TRANSFER.NEW",
  "object": {
    "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645",
    "created_at": "2025-01-22T14:10:00.00Z",
    "updated_at": "2025-01-22T14:12:34.56Z",
    "direction": "INCOMING",
    "status": "NEW",
    "transfer_type": "NO_OWNER_CHANGE",
    "instruments": [ … ],
    "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e",
    "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4",
    "settlement_reference": "b82dc5985558fdr2",
    "counterparty": { … }
  },
  "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c"
}

Responses

Request has been processed successfully.

Securities Transfers

All Securities Transfers related paths.

OperationsWebhooks

Webhook Subscriptions

All webhook subscriptions related paths.

Operations

Tests

All test related paths.

Operations