Skip to content
API Reference/
/
Get an order by ID

Upvest Investment API (1.75.0)

Upvest Investment API.

Download OpenAPI description
api.json
api.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 Exemptions

All tax exemptions related paths

OperationsWebhooks

Tax Collections

All tax collections related paths

Webhooks

Tax Wrappers

All tax wrappers related paths

OperationsWebhooks

Instruments

All instrument related paths.

OperationsWebhooks

Price Data

All price data related paths.

Operations

Orders

All order related paths.

OperationsWebhooks

Place an order

Request

Places a new order. After the creation request for the order is accepted, further processing takes place asynchronously.

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

The ID of the user

account_idstring(uuid)required

The ID of the account that owns the order

sidestringrequired

Side of the order.

  • BUY -
  • SELL -
Enum"BUY""SELL"
instrument_idstring^[A-Z]{2}[A-Z0-9]{9}[0-9]$required

International securities identification number defined by ISO 6166.

instrument_id_typestringrequired

The type of the ID used in the request.

  • ISIN -
Default "ISIN"
Value"ISIN"
cash_amountstring^[0-9]{1,9}(\.[0-9]{2})?$
currencystring
Enum"EUR""GBP"
order_typestring

Type of the order.

  • MARKET -
  • LIMIT -
  • STOP -
Enum"MARKET""LIMIT""STOP"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$
user_instrument_fit_acknowledgementboolean

Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade.

limit_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
stop_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
expiry_datestring^[0-9]{4}-[0-9]{2}-[0-9]{2}$
client_referencestring<= 100 characters

Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.

execution_flowstring

Execution flow that the order processing goes through. If no value is specified, the default value is assumed - STRAIGHT_THROUGH.

  • STRAIGHT_THROUGH -
  • BLOCK -
Enum"STRAIGHT_THROUGH""BLOCK"
fee_configurationArray of objects

fee configuration

curl -i -X POST \
  https://sandbox.upvest.co/orders \
  -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 '{
    "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
    "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
    "cash_amount": "1000",
    "currency": "EUR",
    "side": "BUY",
    "instrument_id": "US0378331005",
    "instrument_id_type": "ISIN",
    "order_type": "MARKET",
    "user_instrument_fit_acknowledgement": true,
    "limit_price": "",
    "stop_price": ""
  }'

Responses

The request for the order creation has been accepted for processing.

Headers
upvest-request-idstring(uuid)required
Example: "169ae4c7-ebd7-4041-94da-25369653eba7"
Bodyapplication/json
idstring(uuid)required
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

user_idstring(uuid)required

The ID of the user

account_idstring(uuid)required

The ID of the account that owns the order

cash_amountstring^[0-9]{1,9}(\.[0-9]{2})?$required
currencystringrequired
Enum"EUR""GBP"
sidestringrequired

Side of the order.

  • BUY -
  • SELL -
Enum"BUY""SELL"
instrument_idstring^[A-Z]{2}[A-Z0-9]{9}[0-9]$required

International securities identification number defined by ISO 6166.

instrument_id_typestringrequired

The type of the ID used in the request.

  • ISIN -
Default "ISIN"
Value"ISIN"
order_typestringrequired

Type of the order.

  • MARKET -
  • LIMIT -
  • STOP -
Enum"MARKET""LIMIT""STOP"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required
statusstringrequired

The execution status of the order.

  • NEW -
  • PROCESSING -
  • FILLED -
  • CANCELLED -
Enum"NEW""PROCESSING""FILLED""CANCELLED"
feestring^[0-9]{0,63}(\.[0-9]{1,27})?$required
initiation_flowstringrequired

Initiation flow used during order creation, i.e. what triggered the order.

  • API -
  • PORTFOLIO -
  • CASH_DIVIDEND_REINVESTMENT -
  • PORTFOLIO_REBALANCING -
  • SELL_TO_COVER_FEES -
  • SELL_TO_COVER_TAXES -
  • ACCOUNT_LIQUIDATION -
  • UPVEST_OPERATIONS -
  • SAVINGS_PLAN -
Enum"API""PORTFOLIO""CASH_DIVIDEND_REINVESTMENT""PORTFOLIO_REBALANCING""SELL_TO_COVER_FEES""SELL_TO_COVER_TAXES""ACCOUNT_LIQUIDATION""UPVEST_OPERATIONS""SAVINGS_PLAN"
executionsArray of objectsrequired

Order executions associated with this order

idstring(uuid)required
cash_amountstring^[0-9]{1,9}(\.[0-9]{2})?$required
share_quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required
pricestring^[0-9]{0,63}(\.[0-9]{1,4})?$required
transaction_timestring(date-time)required
taxesArray of objectsrequired
typestringrequired

Tax type

  • TOTAL -
Default "TOTAL"
Value"TOTAL"
amountstring^[0-9]{0,63}(\.[0-9]{1,27})?$required
order_idstring(uuid)required
statusstringrequired

Execution status of the Execution.

  • FILLED -
  • SETTLED -
  • CANCELLED -
Enum"FILLED""SETTLED""CANCELLED"
sidestringrequired

Side of the execution.

  • BUY -
  • SELL -
Enum"BUY""SELL"
currencystringrequired

Alphabetic three-letter ISO 4217 currency code.

  • EUR - Euro
  • GBP - British Pound
Enum"EUR""GBP"
venue_idstring(uuid)required

The ID of the venue

settlement_datestring^[0-9]{4}-[0-9]{2}-[0-9]{2}$
client_referencestring<= 100 charactersrequired

Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.

user_instrument_fit_acknowledgementboolean

Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade.

limit_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
stop_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
expiry_datestring^[0-9]{4}-[0-9]{2}-[0-9]{2}$
cancellation_reasonstring

Reason for Order cancellation. The field is present in case the Order has a status of CANCELLED.

  • CANCELLED_BY_CLIENT -
  • CANCELLED_BY_UPVEST_OPERATIONS -
  • CANCELLED_BY_TRADING_PARTNER -
  • CANCELLED_BY_UPVEST_PLATFORM -
Enum"CANCELLED_BY_CLIENT""CANCELLED_BY_UPVEST_OPERATIONS""CANCELLED_BY_TRADING_PARTNER""CANCELLED_BY_UPVEST_PLATFORM"
execution_flowstring

Execution flow that the order processing goes through. If no value is specified, the default value is assumed - STRAIGHT_THROUGH.

  • STRAIGHT_THROUGH -
  • BLOCK -
Enum"STRAIGHT_THROUGH""BLOCK"
fee_configurationArray of objects

fee configuration

Response
application/json
{
  "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "cash_amount": "1000",
  "currency": "EUR",
  "side": "BUY",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "order_type": "MARKET",
  "quantity": "0",
  "user_instrument_fit_acknowledgement": true,
  "limit_price": "",
  "stop_price": "",
  "status": "NEW",
  "fee": "0.0",
  "executions": [],
  "client_reference": "",
  "initiation_flow": "API"
}

Get an order by ID

Request

Returns the order specified by its ID.

Security
oauth-client-credentials
Path
order_idstring(uuid)required
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/orders/{order_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

OK

Headers
upvest-request-idstring(uuid)required
Example: "169ae4c7-ebd7-4041-94da-25369653eba7"
Bodyapplication/json
idstring(uuid)required
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

user_idstring(uuid)required

The ID of the user

account_idstring(uuid)required

The ID of the account that owns the order

cash_amountstring^[0-9]{1,9}(\.[0-9]{2})?$required
currencystringrequired
Enum"EUR""GBP"
sidestringrequired

Side of the order.

  • BUY -
  • SELL -
Enum"BUY""SELL"
instrument_idstring^[A-Z]{2}[A-Z0-9]{9}[0-9]$required

International securities identification number defined by ISO 6166.

instrument_id_typestringrequired

The type of the ID used in the request.

  • ISIN -
Default "ISIN"
Value"ISIN"
order_typestringrequired

Type of the order.

  • MARKET -
  • LIMIT -
  • STOP -
Enum"MARKET""LIMIT""STOP"
quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required
statusstringrequired

The execution status of the order.

  • NEW -
  • PROCESSING -
  • FILLED -
  • CANCELLED -
Enum"NEW""PROCESSING""FILLED""CANCELLED"
feestring^[0-9]{0,63}(\.[0-9]{1,27})?$required
initiation_flowstringrequired

Initiation flow used during order creation, i.e. what triggered the order.

  • API -
  • PORTFOLIO -
  • CASH_DIVIDEND_REINVESTMENT -
  • PORTFOLIO_REBALANCING -
  • SELL_TO_COVER_FEES -
  • SELL_TO_COVER_TAXES -
  • ACCOUNT_LIQUIDATION -
  • UPVEST_OPERATIONS -
  • SAVINGS_PLAN -
Enum"API""PORTFOLIO""CASH_DIVIDEND_REINVESTMENT""PORTFOLIO_REBALANCING""SELL_TO_COVER_FEES""SELL_TO_COVER_TAXES""ACCOUNT_LIQUIDATION""UPVEST_OPERATIONS""SAVINGS_PLAN"
executionsArray of objectsrequired

Order executions associated with this order

idstring(uuid)required
cash_amountstring^[0-9]{1,9}(\.[0-9]{2})?$required
share_quantitystring^[0-9]{0,63}(\.[0-9]{1,27})?$required
pricestring^[0-9]{0,63}(\.[0-9]{1,4})?$required
transaction_timestring(date-time)required
taxesArray of objectsrequired
typestringrequired

Tax type

  • TOTAL -
Default "TOTAL"
Value"TOTAL"
amountstring^[0-9]{0,63}(\.[0-9]{1,27})?$required
order_idstring(uuid)required
statusstringrequired

Execution status of the Execution.

  • FILLED -
  • SETTLED -
  • CANCELLED -
Enum"FILLED""SETTLED""CANCELLED"
sidestringrequired

Side of the execution.

  • BUY -
  • SELL -
Enum"BUY""SELL"
currencystringrequired

Alphabetic three-letter ISO 4217 currency code.

  • EUR - Euro
  • GBP - British Pound
Enum"EUR""GBP"
venue_idstring(uuid)required

The ID of the venue

settlement_datestring^[0-9]{4}-[0-9]{2}-[0-9]{2}$
client_referencestring<= 100 charactersrequired

Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.

user_instrument_fit_acknowledgementboolean

Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade.

limit_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
stop_pricestring^[0-9]{0,63}(\.[0-9]{1,27})?$
expiry_datestring^[0-9]{4}-[0-9]{2}-[0-9]{2}$
cancellation_reasonstring

Reason for Order cancellation. The field is present in case the Order has a status of CANCELLED.

  • CANCELLED_BY_CLIENT -
  • CANCELLED_BY_UPVEST_OPERATIONS -
  • CANCELLED_BY_TRADING_PARTNER -
  • CANCELLED_BY_UPVEST_PLATFORM -
Enum"CANCELLED_BY_CLIENT""CANCELLED_BY_UPVEST_OPERATIONS""CANCELLED_BY_TRADING_PARTNER""CANCELLED_BY_UPVEST_PLATFORM"
execution_flowstring

Execution flow that the order processing goes through. If no value is specified, the default value is assumed - STRAIGHT_THROUGH.

  • STRAIGHT_THROUGH -
  • BLOCK -
Enum"STRAIGHT_THROUGH""BLOCK"
fee_configurationArray of objects

fee configuration

Response
application/json
{
  "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "cash_amount": "56.65",
  "currency": "EUR",
  "side": "BUY",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "order_type": "MARKET",
  "quantity": "0.05",
  "user_instrument_fit_acknowledgement": true,
  "limit_price": "",
  "stop_price": "",
  "status": "NEW",
  "fee": "0.5",
  "executions": [],
  "client_reference": "",
  "initiation_flow": "API",
  "execution_flow": "STRAIGHT_THROUGH"
}

Cancel an order by ID

Request

Cancels an order specified by its ID. It is possible to cancel an order in the NEW or PROCESSING status. Once a cancellation has been accepted, the further processing steps take place asynchronously and depending on the respective order status.

Security
oauth-client-credentials
Path
order_idstring(uuid)required
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 DELETE \
  'https://sandbox.upvest.co/orders/{order_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

The order cancelling request is accepted.

Headers
upvest-request-idstring(uuid)required
Example: "169ae4c7-ebd7-4041-94da-25369653eba7"
Bodyapplication/json
idstring(uuid)required
Response
application/json
{
  "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c"
}

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

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

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

Webhook Subscriptions

All webhook subscriptions related paths.

Operations

Virtual Bank Accounts

All virtual bank accounts related paths

OperationsWebhooks

Tests

All test related paths.

Operations