Positions

Download Spec

All positions related paths.

List positions

get /accounts/{account_id}/positions

List of account positions

OAuth2 oauth-client-credentials

Required Scopes:

positions:read

All Scopes

account_liquidations:admin · Trigger/read/cancel accounts liquidations
account_liquidations:read · Read accounts liquidations
account_returns:read · Read accounts returns
accounts:admin · Create/update/delete accounts and account groups
accounts:read · Read accounts and account groups
checks:admin · Create checks
checks:read · Read checks
credit_fundings:read · Credit Fundings read operations
fees:admin · Create and read fee operations
fees:read · Read fee operations
instruments:read · Read instruments
mandates:admin · Create/update/delete mandates
mandates:read · Read mandates
orders:admin · Create/update/delete orders
orders:read · Read orders
payments:admin · Payins and withdrawal operations
payments:read · Payins and withdrawal read operations
portfolios:admin · Modify portfolios
portfolios:read · Read portfolios
positions:read · Read positions
reference_accounts:admin · Create/update/delete reference accounts
reference_accounts:read · Read reference accounts
reports:read · Read reports
taxes:admin · Modify tax residencies
taxes:read · Read tax residencies
topups:admin · Topups operations
topups:read · Topups read operations
transactions:read · Read cash and securities transactions
users:admin · Create/update/delete users
users:read · Read users
valuations:read · Read valuations
webhooks:admin · Create/update/delete webhooks
webhooks:read · Read webhooks

Flow Type:: Client Credentials

Token URL:: https://sandbox.upvest.co/auth/token

upvest-client-id

string

uuid

required

Tenant Client ID

Example: "ebabcf4d-61c3-4942-875c-e265a7c2d062"

authorization

string

^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=="

signature

string

required

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

signature-input

string

required

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

upvest-api-version

string

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

Default: "1"
Enum: 1
Example: 1

account_id

string

uuid

required

Account unique identifier.

offset

int

i32

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

Min: 0

limit

int

i32

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

Default: 100
Min: 0
Max: 1000

Response

Examples Schema

Response

{
  "data": [
    {
      "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
      "available_for_trading": "5.4",
      "instrument": {
        "isin": "US0378331005",
        "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
      },
      "locked_for_trading": "5",
      "pending_settlement": "0",
      "quantity": "10.4"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 100,
    "offset": 0,
    "order": "ASC",
    "sort": "id",
    "total_count": 1
  }
}

Bad Request. The incoming request had a malformed parameter/object.

{
  "status": 400,
  "type": "bad_request"
}

Unauthorized. The caller has not been authenticated.

{
  "status": 401,
  "type": "unauthorized"
}

Forbidden. The caller has been authenticated but is not allowed to take the requested action.

{
  "status": 403,
  "type": "forbidden"
}

Not Found. The requested resource could not be found.

{
  "status": 404,
  "type": "not_found"
}

Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

{
  "status": 406,
  "type": "not_acceptable"
}

Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

{
  "status": 429,
  "type": "too_many_requests"
}

Internal Server Error. The service encountered an unexpected error.

{
  "status": 500,
  "type": "internal_server_error"
}

Service Unavailable. The service handling for this request cannot be reached at this time.

{
  "status": 503,
  "type": "method_not_allowed"
}

Gateway Timeout. The service gateway has reached its internal timeout.

{
  "status": 504,
  "type": "gateway_timeout"
}

data

array[object]

required

object

account_id

string

uuid

required

Account unique identifier.

instrument

object (instrument)

required

uuid

string

uuid

required

Instrument unique identifier.

isin

string

^[A-Z]{2}[A-Z0-9]{9}[0-9]$

International securities identification number defined by ISO 6166.

quantity

string

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

required

locked_for_trading

string

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

required

pending_settlement

string

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

required

available_for_trading

string

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

required

Retrieve position

get /accounts/{account_id}/positions/{instrument_id}

Retrieve an account position

OAuth2 oauth-client-credentials

Required Scopes:

positions:read

All Scopes

account_liquidations:admin · Trigger/read/cancel accounts liquidations
account_liquidations:read · Read accounts liquidations
account_returns:read · Read accounts returns
accounts:admin · Create/update/delete accounts and account groups
accounts:read · Read accounts and account groups
checks:admin · Create checks
checks:read · Read checks
credit_fundings:read · Credit Fundings read operations
fees:admin · Create and read fee operations
fees:read · Read fee operations
instruments:read · Read instruments
mandates:admin · Create/update/delete mandates
mandates:read · Read mandates
orders:admin · Create/update/delete orders
orders:read · Read orders
payments:admin · Payins and withdrawal operations
payments:read · Payins and withdrawal read operations
portfolios:admin · Modify portfolios
portfolios:read · Read portfolios
positions:read · Read positions
reference_accounts:admin · Create/update/delete reference accounts
reference_accounts:read · Read reference accounts
reports:read · Read reports
taxes:admin · Modify tax residencies
taxes:read · Read tax residencies
topups:admin · Topups operations
topups:read · Topups read operations
transactions:read · Read cash and securities transactions
users:admin · Create/update/delete users
users:read · Read users
valuations:read · Read valuations
webhooks:admin · Create/update/delete webhooks
webhooks:read · Read webhooks

Flow Type:: Client Credentials

Token URL:: https://sandbox.upvest.co/auth/token

upvest-client-id

string

uuid

required

Tenant Client ID

Example: "ebabcf4d-61c3-4942-875c-e265a7c2d062"

authorization

string

^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=="

signature

string

required

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

signature-input

string

required

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

upvest-api-version

string

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

Default: "1"
Enum: 1
Example: 1

instrument_id

One Of

required

Instrument unique identifier.

International securities identification number with 'isin:' URN namespace

string

^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$

International securities identification number defined by ISO 6166, prefixed with a 'isin:' URN scheme.

Universally Unique IDentifier (UUID) with 'uuid:' URN scheme

string

^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$

Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by RFC 4122.

account_id

string

uuid

required

Account unique identifier.

Response

Examples Schema

Response

{
  "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
  "available_for_trading": "5.4",
  "instrument": {
    "isin": "US0378331005",
    "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
  },
  "locked_for_trading": "5",
  "pending_settlement": "0",
  "quantity": "10.4"
}

{
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "available_for_trading": "0",
  "instrument": {
    "isin": "US0378331005",
    "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
  },
  "locked_for_trading": "10",
  "pending_settlement": "0",
  "quantity": "10"
}

{
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "available_for_trading": "0",
  "instrument": {
    "isin": "US0378331005",
    "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
  },
  "locked_for_trading": "0",
  "pending_settlement": "0",
  "quantity": "0"
}

{
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "available_for_trading": "11.734334663",
  "instrument": {
    "isin": "US0378331005",
    "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
  },
  "locked_for_trading": "0",
  "pending_settlement": "0",
  "quantity": "11.734334663"
}

Unauthorized. The caller has not been authenticated.

{
  "status": 401,
  "type": "unauthorized"
}

Forbidden. The caller has been authenticated but is not allowed to take the requested action.

{
  "status": 403,
  "type": "forbidden"
}

Not Found. The requested resource could not be found.

{
  "status": 404,
  "type": "not_found"
}

Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

{
  "status": 406,
  "type": "not_acceptable"
}

Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

{
  "status": 429,
  "type": "too_many_requests"
}

Internal Server Error. The service encountered an unexpected error.

{
  "status": 500,
  "type": "internal_server_error"
}

Service Unavailable. The service handling for this request cannot be reached at this time.

{
  "status": 503,
  "type": "method_not_allowed"
}

Gateway Timeout. The service gateway has reached its internal timeout.

{
  "status": 504,
  "type": "gateway_timeout"
}

account_id

string

uuid

required

Account unique identifier.

instrument

object (instrument)

required

uuid

string

uuid

required

Instrument unique identifier.

isin

string

^[A-Z]{2}[A-Z0-9]{9}[0-9]$

International securities identification number defined by ISO 6166.

quantity

string

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

required

locked_for_trading

string

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

required

pending_settlement

string

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

required

available_for_trading

string

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

required

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

upvest-request-id

string

uuid

Example: "169ae4c7-ebd7-4041-94da-25369653eba7"

Positions events

webhook

Positions events

created_at

string

date-time

required

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

string

uuid

required

Event unique identifier

object

object (object)

required

account_id

string

uuid

required

Account unique identifier.

available_for_trading

string

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

required

instrument

object (instrument)

required

isin

string

^[A-Z]{2}[A-Z0-9]{9}[0-9]$

International securities identification number defined by ISO 6166.

uuid

string

uuid

required

Instrument unique identifier.

locked_for_trading

string

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

required

pending_settlement

string

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

required

quantity

string

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

required

type

string

required

Event type

Default: "POSITION.UPDATED"
Enum: POSITION.UPDATED

webhook_id

string

uuid

required

Webhook unique identifier.

Request

{
  "created_at": "2021-07-21T14:10:00.00Z",
  "id": "8962b496-8d42-4560-bfab-10490dd1a724",
  "object": {
    "account_id": "c5161455-4d27-4781-bc74-f05532e49a77",
    "available_for_trading": "5.4",
    "instrument": {
      "isin": "US0378331005",
      "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321"
    },
    "locked_for_trading": "5",
    "pending_settlement": "0",
    "quantity": "10.4"
  },
  "type": "POSITION.UPDATED",
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Response

Examples Schema

Request has been processed successfully.

Empty response

No schema

Was this page helpful?