Upvest Investment API

openapi: 3.1.0
info:
  title: Upvest Investment 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
externalDocs:
  description: Upvest API Documentation
  url: https://docs.upvest.co/
servers:
- url: https://api.upvest.co
  description: Production Server
- url: https://sandbox.upvest.co
  description: Sandbox Server
tags:
- name: Account Transfers
  description: >-
    Transfer accounts between entities.
- name: Accounts
  description: >-
    Investment accounts that hold positions and track balances for users.
- name: Authentication
  description: >-
    OAuth 2.0 token management for API access using client credentials flow.
- name: Cash Balances
  description: >-
    View cash balance information for accounts.
- name: Corporate Actions
  description: >-
    View and manage corporate action events on held securities.
- name: Direct Debits
  description: >-
    Manage direct debit funding operations.
- name: Executions
  description: >-
    Track order execution details and fills.
- name: Fee Configurations
  description: >-
    Configure fee structures and schedules.
- name: Fees
  description: >-
    Track and manage fee charges on accounts.
- name: Files
  description: >-
    Access and download generated files such as reports and statements.
- name: Instrument Prices
  description: >-
    Retrieve real-time and historical price data for instruments.
- name: Instruments
  description: >-
    Query available financial instruments and their metadata.
- name: Liquidations
  description: >-
    Manage full or partial account liquidations.
- name: Mandates
  description: >-
    Manage direct debit mandates for accounts.
- name: Order Cancellations
  description: >-
    Cancel pending orders before execution.
- name: Orders
  description: >-
    Place, manage, and track buy and sell orders for instruments.
- name: Portfolio Allocations
  description: >-
    Define and update target allocations within portfolios.
- name: Portfolio Orders
  description: >-
    Place orders against portfolio allocations.
- name: Portfolios
  description: >-
    Create and manage portfolios with custom asset allocations.
- name: Portfolios Rebalancing
  description: >-
    Trigger and track portfolio rebalancing operations.
- name: Positions
  description: >-
    View current holdings and position details for accounts.
- name: Reference Accounts
  description: >-
    Manage reference bank accounts linked to investment accounts.
- name: Reports
  description: >-
    Generate and retrieve user-facing investment reports and statements.
- name: Returns
  description: >-
    Calculate account-level investment returns.
- name: Savings Plans
  description: >-
    Configure automated recurring investments into portfolios or instruments.
- name: Securities Transfers
  description: >-
    Transfer securities between accounts or providers.
- name: Tax Residencies
  description: >-
    Manage tax residency information for users.
- name: Transactions
  description: >-
    View transaction history for accounts.
- name: Treasury Reports
  description: >-
    Access treasury-level reporting for institutional oversight.
- name: User Checks
  description: >-
    Compliance and verification checks on users.
- name: User Identifiers
  description: >-
    Manage external identifiers associated with users.
- name: Users
  description: >-
    Manage end users including onboarding, identity verification, and profile
    management.
- name: Valuations
  description: >-
    Retrieve account and position valuations.
- name: Webhook Subscriptions
  description: >-
    Register, update, and manage webhook subscriptions for event notifications.
- name: Withdrawals
  description: >-
    Process cash withdrawals from investment accounts.
security:
- oauth2ClientCredentials: []
paths:
  /auth/token:
    post:
      operationId: createAccessToken
      summary: Upvest Create an access token
      description: >-
        Obtain an OAuth 2.0 access token using client credentials. The returned
        opaque access token is used to authenticate subsequent API requests. You
        must specify the required scopes for the endpoints you intend to call.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              - client_id
              - client_secret
              - scope
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  description: >-
                    The OAuth 2.0 grant type. Must be client_credentials.
                client_id:
                  type: string
                  description: >-
                    The client identifier issued during onboarding.
                client_secret:
                  type: string
                  description: >-
                    The client secret issued during onboarding.
                scope:
                  type: string
                  description: >-
                    A space-separated list of scopes to request.
      responses:
        '200':
          description: Access token successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
              examples:
                createAccessToken200Example:
                  summary: Default createAccessToken 200 response
                  x-microcks-default: true
                  value:
                    access_token: eyJhbGciOiJSUzI1NiJ9.example
                    token_type: bearer
                    expires_in: 3600
                    scope: users:read accounts:read
        '401':
          description: Invalid client credentials or missing scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createAccessToken401Example:
                  summary: Default createAccessToken 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users:
    get:
      operationId: listUsers
      summary: Upvest List users
      description: >-
        Retrieve a paginated list of all onboarded users. Supports filtering
        and pagination parameters.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      first_name: {}
                      last_name: {}
                      email: {}
                      date_of_birth: {}
                      nationality: {}
                      address: {}
                      status: {}
                      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:
                listUsers401Example:
                  summary: Default listUsers 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: createUser
      summary: Upvest Create a user
      description: >-
        Onboard a new user to the investment platform. The user must pass
        identity verification and compliance checks before trading is enabled.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
            examples:
              createUserRequestExample:
                summary: Default createUser request
                x-microcks-default: true
                value:
                  first_name: Example Name
                  last_name: Example Name
                  email: [email protected]
                  date_of_birth: '2025-03-15'
                  nationality: DE
                  address:
                    street: {}
                    additional_line: {}
                    city: {}
                    postal_code: {}
                    state: {}
                    country: {}
      responses:
        '201':
          description: User successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                createUser201Example:
                  summary: Default createUser 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    first_name: Example Name
                    last_name: Example Name
                    email: [email protected]
                    date_of_birth: '2025-03-15'
                    nationality: DE
                    address:
                      street: {}
                      additional_line: {}
                      city: {}
                      postal_code: {}
                      state: {}
                      country: {}
                    status: PENDING
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createUser400Example:
                  summary: Default createUser 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:
                createUser401Example:
                  summary: Default createUser 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user_id}:
    get:
      operationId: retrieveUser
      summary: Upvest Retrieve a user
      description: >-
        Retrieve details for a specific user by their unique identifier.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                retrieveUser200Example:
                  summary: Default retrieveUser 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    first_name: Example Name
                    last_name: Example Name
                    email: [email protected]
                    date_of_birth: '2025-03-15'
                    nationality: DE
                    address:
                      street: {}
                      additional_line: {}
                      city: {}
                      postal_code: {}
                      state: {}
                      country: {}
                    status: PENDING
                    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:
                retrieveUser401Example:
                  summary: Default retrieveUser 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveUser404Example:
                  summary: Default retrieveUser 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateUser
      summary: Upvest Update a user
      description: >-
        Update profile information for an existing user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
            examples:
              updateUserRequestExample:
                summary: Default updateUser request
                x-microcks-default: true
                value:
                  first_name: Example Name
                  last_name: Example Name
                  email: [email protected]
                  address:
                    street: {}
                    additional_line: {}
                    city: {}
                    postal_code: {}
                    state: {}
                    country: {}
      responses:
        '200':
          description: User successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                updateUser200Example:
                  summary: Default updateUser 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    first_name: Example Name
                    last_name: Example Name
                    email: [email protected]
                    date_of_birth: '2025-03-15'
                    nationality: DE
                    address:
                      street: {}
                      additional_line: {}
                      city: {}
                      postal_code: {}
                      state: {}
                      country: {}
                    status: PENDING
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updateUser400Example:
                  summary: Default updateUser 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:
                updateUser401Example:
                  summary: Default updateUser 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updateUser404Example:
                  summary: Default updateUser 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user_id}/identifiers:
    get:
      operationId: listUserIdentifiers
      summary: Upvest List user identifiers
      description: >-
        Retrieve all external identifiers associated with a user.
      tags:
      - User Identifiers
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of user identifiers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserIdentifier'
              examples:
                listUserIdentifiers200Example:
                  summary: Default listUserIdentifiers 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      type: {}
                      value: {}
                      created_at: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listUserIdentifiers401Example:
                  summary: Default listUserIdentifiers 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listUserIdentifiers404Example:
                  summary: Default listUserIdentifiers 404 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: createUserIdentifier
      summary: Upvest Create a user identifier
      description: >-
        Add an external identifier to a user record.
      tags:
      - User Identifiers
      parameters:
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdentifierCreate'
            examples:
              createUserIdentifierRequestExample:
                summary: Default createUserIdentifier request
                x-microcks-default: true
                value:
                  type: standard
                  value: example-value
      responses:
        '201':
          description: Identifier created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentifier'
              examples:
                createUserIdentifier201Example:
                  summary: Default createUserIdentifier 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    value: example-value
                    created_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createUserIdentifier400Example:
                  summary: Default createUserIdentifier 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:
                createUserIdentifier401Example:
                  summary: Default createUserIdentifier 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user_id}/identifiers/{identifier_id}:
    get:
      operationId: retrieveUserIdentifier
      summary: Upvest Retrieve a user identifier
      description: >-
        Retrieve a specific external identifier for a user.
      tags:
      - User Identifiers
      parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/IdentifierId'
      responses:
        '200':
          description: User identifier details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentifier'
              examples:
                retrieveUserIdentifier200Example:
                  summary: Default retrieveUserIdentifier 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    value: example-value
                    created_at: '2025-03-15T14:30:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveUserIdentifier401Example:
                  summary: Default retrieveUserIdentifier 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveUserIdentifier404Example:
                  summary: Default retrieveUserIdentifier 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateUserIdentifier
      summary: Upvest Update a user identifier
      description: >-
        Update an existing external identifier for a user.
      tags:
      - User Identifiers
      parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/IdentifierId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdentifierUpdate'
            examples:
              updateUserIdentifierRequestExample:
                summary: Default updateUserIdentifier request
                x-microcks-default: true
                value:
                  value: example-value
      responses:
        '200':
          description: Identifier updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentifier'
              examples:
                updateUserIdentifier200Example:
                  summary: Default updateUserIdentifier 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    value: example-value
                    created_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updateUserIdentifier400Example:
                  summary: Default updateUserIdentifier 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:
                updateUserIdentifier401Example:
                  summary: Default updateUserIdentifier 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user_id}/checks:
    get:
      operationId: listUserChecks
      summary: Upvest List user checks
      description: >-
        Retrieve compliance and verification checks performed on a user.
      tags:
      - User Checks
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of user checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserCheck'
              examples:
                listUserChecks200Example:
                  summary: Default listUserChecks 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      type: {}
                      status: {}
                      created_at: {}
                      completed_at: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listUserChecks401Example:
                  summary: Default listUserChecks 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user_id}/tax_residencies:
    get:
      operationId: listTaxResidencies
      summary: Upvest List tax residencies
      description: >-
        Retrieve tax residency information for a user.
      tags:
      - Tax Residencies
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of tax residencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxResidency'
              examples:
                listTaxResidencies200Example:
                  summary: Default listTaxResidencies 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      country: {}
                      tax_identification_number: {}
                      created_at: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listTaxResidencies401Example:
                  summary: Default listTaxResidencies 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: createTaxResidency
      summary: Upvest Create a tax residency
      description: >-
        Add a tax residency record for a user.
      tags:
      - Tax Residencies
      parameters:
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxResidencyCreate'
            examples:
              createTaxResidencyRequestExample:
                summary: Default createTaxResidency request
                x-microcks-default: true
                value:
                  country: DE
                  tax_identification_number: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '201':
          description: Tax residency created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxResidency'
              examples:
                createTaxResidency201Example:
                  summary: Default createTaxResidency 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    country: DE
                    tax_identification_number: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    created_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createTaxResidency400Example:
                  summary: Default createTaxResidency 400 response
            

# --- truncated at 32 KB (218 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upvest/refs/heads/main/openapi/upvest-investment-api-openapi.yml