openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Orders 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: Orders
  description: Place, manage, and track buy and sell orders for instruments.
paths:
  /orders:
    get:
      operationId: listOrders
      summary: Upvest List orders
      description: Retrieve a paginated list of orders. Supports filtering by account, status, and other criteria.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - name: account_id
        in: query
        description: Filter orders by account identifier.
        schema:
          type: string
          format: uuid
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      - name: status
        in: query
        description: Filter orders by status.
        schema:
          type: string
          enum:
          - NEW
          - PROCESSING
          - FILLED
          - CANCELLED
          - REJECTED
        example: NEW
      responses:
        '200':
          description: A paginated list of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listOrders200Example:
                  summary: Default listOrders 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      account_id: {}
                      user_id: {}
                      instrument_id: {}
                      side: {}
                      type: {}
                      status: {}
                      quantity: {}
                      cash_amount: {}
                      limit_price: {}
                      stop_price: {}
                      currency: {}
                      created_at: {}
                      updated_at: {}
                    meta:
                      offset: 0
                      limit: 20
                      count: 100
                      total: 100
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listOrders401Example:
                  summary: Default listOrders 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createOrder
      summary: Upvest Place an order
      description: Place a new buy or sell order for a financial instrument. Orders are processed asynchronously and their status can be tracked via webhooks or polling.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
            examples:
              createOrderRequestExample:
                summary: Default createOrder request
                x-microcks-default: true
                value:
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  side: BUY
                  type: MARKET
                  quantity: example-value
                  cash_amount: example-value
                  limit_price: example-value
                  stop_price: example-value
                  currency: EUR
      responses:
        '201':
          description: Order successfully placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                createOrder201Example:
                  summary: Default createOrder 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    side: BUY
                    type: MARKET
                    status: NEW
                    quantity: example-value
                    cash_amount: example-value
                    limit_price: example-value
                    stop_price: example-value
                    currency: EUR
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid order request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createOrder400Example:
                  summary: Default createOrder 400 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createOrder401Example:
                  summary: Default createOrder 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{order_id}:
    get:
      operationId: retrieveOrder
      summary: Upvest Retrieve an order
      description: Retrieve details for a specific order including current status and execution information.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                retrieveOrder200Example:
                  summary: Default retrieveOrder 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    side: BUY
                    type: MARKET
                    status: NEW
                    quantity: example-value
                    cash_amount: example-value
                    limit_price: example-value
                    stop_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:
                retrieveOrder401Example:
                  summary: Default retrieveOrder 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveOrder404Example:
                  summary: Default retrieveOrder 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:
  schemas:
    Order:
      type: object
      description: A buy or sell order for a financial instrument.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the order.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_id:
          type: string
          format: uuid
          description: The account the order belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        user_id:
          type: string
          format: uuid
          description: The user who placed the order.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        instrument_id:
          type: string
          format: uuid
          description: The instrument being traded.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        side:
          type: string
          enum:
          - BUY
          - SELL
          description: Whether this is a buy or sell order.
          example: BUY
        type:
          type: string
          enum:
          - MARKET
          - LIMIT
          - STOP
          description: The order type.
          example: MARKET
        status:
          type: string
          enum:
          - NEW
          - PROCESSING
          - FILLED
          - CANCELLED
          - REJECTED
          description: The current status of the order.
          example: NEW
        quantity:
          type: string
          description: The quantity of shares to trade as a decimal string.
          example: example-value
        cash_amount:
          type: string
          description: The cash amount to invest as a decimal string.
          example: example-value
        limit_price:
          type: string
          description: The limit price for limit orders as a decimal string.
          example: example-value
        stop_price:
          type: string
          description: The stop price for stop orders as a decimal string.
          example: example-value
        currency:
          type: string
          description: The order currency as an ISO 4217 code.
          pattern: ^[A-Z]{3}$
          example: EUR
        created_at:
          type: string
          format: date-time
          description: When the order was placed.
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the order was last updated.
          example: '2025-03-15T14:30:00Z'
    PaginationMeta:
      type: object
      description: Pagination metadata for list responses.
      properties:
        offset:
          type: integer
          description: The current offset.
          example: 0
        limit:
          type: integer
          description: The page size.
          example: 20
        count:
          type: integer
          description: The total number of items in the current page.
          example: 100
        total:
          type: integer
          description: The total number of items available.
          example: 100
    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
    OrderCreate:
      type: object
      description: Request body for placing an order.
      required:
      - account_id
      - instrument_id
      - side
      - type
      properties:
        account_id:
          type: string
          format: uuid
          description: The account to place the order for.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        instrument_id:
          type: string
          format: uuid
          description: The instrument to trade.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        side:
          type: string
          enum:
          - BUY
          - SELL
          description: Whether to buy or sell.
          example: BUY
        type:
          type: string
          enum:
          - MARKET
          - LIMIT
          - STOP
          description: The order type.
          example: MARKET
        quantity:
          type: string
          description: The quantity of shares to trade as a decimal string.
          example: example-value
        cash_amount:
          type: string
          description: The cash amount to invest as a decimal string.
          example: example-value
        limit_price:
          type: string
          description: The limit price for limit orders as a decimal string.
          example: example-value
        stop_price:
          type: string
          description: The stop price for stop orders as a decimal string.
          example: example-value
        currency:
          type: string
          description: The order currency as an ISO 4217 code.
          pattern: ^[A-Z]{3}$
          example: EUR
  parameters:
    Offset:
      name: offset
      in: query
      description: The number of items to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Limit:
      name: limit
      in: query
      description: The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OrderId:
      name: order_id
      in: path
      required: true
      description: The unique identifier of the order.
      schema:
        type: string
        format: uuid
  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/