openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Accounts 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: Accounts
  description: Investment accounts that hold positions and track balances for users.
paths:
  /users/{user_id}/accounts:
    get:
      operationId: listUserAccounts
      summary: Upvest List accounts for a user
      description: Retrieve all investment accounts belonging to a specific user.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of user accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listUserAccounts200Example:
                  summary: Default listUserAccounts 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      user_id: {}
                      account_group_id: {}
                      type: {}
                      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:
                listUserAccounts401Example:
                  summary: Default listUserAccounts 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts:
    get:
      operationId: listAccounts
      summary: Upvest List accounts
      description: Retrieve a paginated list of all investment accounts.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listAccounts200Example:
                  summary: Default listAccounts 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      user_id: {}
                      account_group_id: {}
                      type: {}
                      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:
                listAccounts401Example:
                  summary: Default listAccounts 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: createAccount
      summary: Upvest Create an account
      description: Open a new investment account for a user.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
            examples:
              createAccountRequestExample:
                summary: Default createAccount request
                x-microcks-default: true
                value:
                  user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  account_group_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  type: standard
      responses:
        '201':
          description: Account successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                createAccount201Example:
                  summary: Default createAccount 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_group_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    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:
                createAccount400Example:
                  summary: Default createAccount 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:
                createAccount401Example:
                  summary: Default createAccount 401 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}:
    get:
      operationId: retrieveAccount
      summary: Upvest Retrieve an account
      description: Retrieve details for a specific investment account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                retrieveAccount200Example:
                  summary: Default retrieveAccount 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_group_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    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:
                retrieveAccount401Example:
                  summary: Default retrieveAccount 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:
                retrieveAccount404Example:
                  summary: Default retrieveAccount 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: updateAccount
      summary: Upvest Update an account
      description: Update metadata or settings for an existing investment account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
            examples:
              updateAccountRequestExample:
                summary: Default updateAccount request
                x-microcks-default: true
                value:
                  type: standard
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                updateAccount200Example:
                  summary: Default updateAccount 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_group_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    type: standard
                    status: PENDING
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updateAccount400Example:
                  summary: Default updateAccount 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:
                updateAccount401Example:
                  summary: Default updateAccount 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:
                updateAccount404Example:
                  summary: Default updateAccount 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: closeAccount
      summary: Upvest Close an account
      description: Close an investment account. The account must have no open positions or pending orders.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '204':
          description: Account successfully closed
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                closeAccount401Example:
                  summary: Default closeAccount 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:
                closeAccount404Example:
                  summary: Default closeAccount 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:
    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
    AccountUpdate:
      type: object
      description: Request body for updating an investment account.
      properties:
        type:
          type: string
          description: The type of investment account.
          example: standard
    AccountCreate:
      type: object
      description: Request body for creating an investment account.
      required:
      - user_id
      - account_group_id
      properties:
        user_id:
          type: string
          format: uuid
          description: The user to create the account for.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_group_id:
          type: string
          format: uuid
          description: The account group to assign the account to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          description: The type of investment account.
          example: standard
    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
    Account:
      type: object
      description: An investment account that holds positions and tracks balances.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the account.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        user_id:
          type: string
          format: uuid
          description: The user who owns this account.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_group_id:
          type: string
          format: uuid
          description: The account group this account belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          description: The type of investment account.
          example: standard
        status:
          type: string
          enum:
          - PENDING
          - OPEN
          - CLOSING
          - CLOSED
          description: The current status of the account.
          example: PENDING
        created_at:
          type: string
          format: date-time
          description: When the account was created.
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the account was last updated.
          example: '2025-03-15T14:30:00Z'
  parameters:
    Offset:
      name: offset
      in: query
      description: The number of items to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    AccountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the account.
      schema:
        type: string
        format: uuid
    UserId:
      name: user_id
      in: path
      required: true
      description: The unique identifier of the user.
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  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/