openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Positions API
  description: The Upvest Investment API provides a unified interface for building embedded investment experiences. It supports placing and managing orders, creating portfolios, configuring savings plans, handling securities transfers, and managing user accounts and positions. The API covers the full order lifecycle with asynchronous processing and webhook notifications for real-time event handling. Financial institutions can use the API to offer fractional investing, automated portfolio management, and localized investment products across European and UK markets.
  version: 1.0.0
  contact:
    name: Upvest Support
    url: https://upvest.co/
  termsOfService: https://upvest.co/legal
servers:
- url: https://api.upvest.co
  description: Production Server
- url: https://sandbox.upvest.co
  description: Sandbox Server
security:
- oauth2ClientCredentials: []
tags:
- name: Positions
  description: View current holdings and position details for accounts.
paths:
  /accounts/{account_id}/positions:
    get:
      operationId: listPositions
      summary: Upvest List positions
      description: Retrieve current holdings and position details for an account.
      tags:
      - Positions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: List of positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Position'
              examples:
                listPositions200Example:
                  summary: Default listPositions 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      account_id: {}
                      instrument_id: {}
                      quantity: {}
                      average_buy_in_price: {}
                      currency: {}
                      created_at: {}
                      updated_at: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listPositions401Example:
                  summary: Default listPositions 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listPositions404Example:
                  summary: Default listPositions 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/positions/{position_id}:
    get:
      operationId: retrievePosition
      summary: Upvest Retrieve a position
      description: Retrieve details for a specific position within an account.
      tags:
      - Positions
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/PositionId'
      responses:
        '200':
          description: Position details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
              examples:
                retrievePosition200Example:
                  summary: Default retrievePosition 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    quantity: example-value
                    average_buy_in_price: example-value
                    currency: EUR
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrievePosition401Example:
                  summary: Default retrievePosition 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrievePosition404Example:
                  summary: Default retrievePosition 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the account.
      schema:
        type: string
        format: uuid
    PositionId:
      name: position_id
      in: path
      required: true
      description: The unique identifier of the position.
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      description: An API error response.
      properties:
        type:
          type: string
          description: The error type identifier.
          example: standard
        status:
          type: integer
          description: The HTTP status code.
          example: 100
        title:
          type: string
          description: A short human-readable summary of the error.
          example: example-value
        detail:
          type: string
          description: A detailed human-readable explanation of the error.
          example: example-value
    Position:
      type: object
      description: A holding of a financial instrument within an account.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the position.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_id:
          type: string
          format: uuid
          description: The account the position belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        instrument_id:
          type: string
          format: uuid
          description: The instrument held.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        quantity:
          type: string
          description: The quantity of shares held as a decimal string.
          example: example-value
        average_buy_in_price:
          type: string
          description: The average buy-in price as a decimal string.
          example: example-value
        currency:
          type: string
          description: The position currency.
          pattern: ^[A-Z]{3}$
          example: EUR
        created_at:
          type: string
          format: date-time
          description: When the position was first established.
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the position was last updated.
          example: '2025-03-15T14:30:00Z'
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials flow. Obtain an access token by providing your client ID and client secret.
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes:
            users:read: Read user data
            users:admin: Onboard and manage users
            accounts:read: Read account data
            accounts:admin: Create and manage accounts
            orders:read: Read order data
            orders:admin: Place and manage orders
            instruments:read: Read instrument data
            portfolios:read: Read portfolio data
            portfolios:admin: Create and manage portfolios
            positions:read: Read position data
            payments:read: Read payment data
            payments:admin: Manage payments and direct debits
            reports:read: Read reports
            webhooks:read: Read webhook subscriptions
            webhooks:admin: Manage webhook subscriptions
            transactions:read: Read transaction data
            fees:read: Read fee data
            fees:admin: Configure fees
externalDocs:
  description: Upvest API Documentation
  url: https://docs.upvest.co/