openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Savings Plans 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: Savings Plans
  description: Configure automated recurring investments into portfolios or instruments.
paths:
  /savings_plans:
    get:
      operationId: listSavingsPlans
      summary: Upvest List savings plans
      description: Retrieve a paginated list of automated savings plans.
      tags:
      - Savings Plans
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of savings plans
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavingsPlan'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listSavingsPlans200Example:
                  summary: Default listSavingsPlans 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      account_id: {}
                      portfolio_id: {}
                      instrument_id: {}
                      cash_amount: {}
                      currency: {}
                      frequency: {}
                      status: {}
                      next_execution_date: {}
                      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:
                listSavingsPlans401Example:
                  summary: Default listSavingsPlans 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: createSavingsPlan
      summary: Upvest Create a savings plan
      description: Create an automated recurring investment plan. Savings plans execute on a defined schedule, investing a specified amount into an instrument or portfolio.
      tags:
      - Savings Plans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavingsPlanCreate'
            examples:
              createSavingsPlanRequestExample:
                summary: Default createSavingsPlan request
                x-microcks-default: true
                value:
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  portfolio_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  cash_amount: example-value
                  currency: EUR
                  frequency: WEEKLY
      responses:
        '201':
          description: Savings plan created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlan'
              examples:
                createSavingsPlan201Example:
                  summary: Default createSavingsPlan 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    portfolio_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    cash_amount: example-value
                    currency: EUR
                    frequency: WEEKLY
                    status: ACTIVE
                    next_execution_date: '2025-03-15'
                    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:
                createSavingsPlan400Example:
                  summary: Default createSavingsPlan 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:
                createSavingsPlan401Example:
                  summary: Default createSavingsPlan 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /savings_plans/{savings_plan_id}:
    get:
      operationId: retrieveSavingsPlan
      summary: Upvest Retrieve a savings plan
      description: Retrieve details for a specific savings plan.
      tags:
      - Savings Plans
      parameters:
      - $ref: '#/components/parameters/SavingsPlanId'
      responses:
        '200':
          description: Savings plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlan'
              examples:
                retrieveSavingsPlan200Example:
                  summary: Default retrieveSavingsPlan 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    portfolio_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    cash_amount: example-value
                    currency: EUR
                    frequency: WEEKLY
                    status: ACTIVE
                    next_execution_date: '2025-03-15'
                    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:
                retrieveSavingsPlan401Example:
                  summary: Default retrieveSavingsPlan 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Savings plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveSavingsPlan404Example:
                  summary: Default retrieveSavingsPlan 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: updateSavingsPlan
      summary: Upvest Update a savings plan
      description: Update the configuration of an existing savings plan.
      tags:
      - Savings Plans
      parameters:
      - $ref: '#/components/parameters/SavingsPlanId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavingsPlanUpdate'
            examples:
              updateSavingsPlanRequestExample:
                summary: Default updateSavingsPlan request
                x-microcks-default: true
                value:
                  cash_amount: example-value
                  frequency: WEEKLY
                  status: ACTIVE
      responses:
        '200':
          description: Savings plan updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlan'
              examples:
                updateSavingsPlan200Example:
                  summary: Default updateSavingsPlan 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    portfolio_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    cash_amount: example-value
                    currency: EUR
                    frequency: WEEKLY
                    status: ACTIVE
                    next_execution_date: '2025-03-15'
                    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:
                updateSavingsPlan400Example:
                  summary: Default updateSavingsPlan 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:
                updateSavingsPlan401Example:
                  summary: Default updateSavingsPlan 401 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: deleteSavingsPlan
      summary: Upvest Delete a savings plan
      description: Cancel and remove an automated savings plan.
      tags:
      - Savings Plans
      parameters:
      - $ref: '#/components/parameters/SavingsPlanId'
      responses:
        '204':
          description: Savings plan deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                deleteSavingsPlan401Example:
                  summary: Default deleteSavingsPlan 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Savings plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                deleteSavingsPlan404Example:
                  summary: Default deleteSavingsPlan 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:
    SavingsPlanCreate:
      type: object
      description: Request body for creating a savings plan.
      required:
      - account_id
      - cash_amount
      - currency
      - frequency
      properties:
        account_id:
          type: string
          format: uuid
          description: The account to create the plan for.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        portfolio_id:
          type: string
          format: uuid
          description: The portfolio to invest into.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        instrument_id:
          type: string
          format: uuid
          description: The instrument to invest into.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        cash_amount:
          type: string
          description: The recurring investment amount.
          example: example-value
        currency:
          type: string
          description: The currency as an ISO 4217 code.
          pattern: ^[A-Z]{3}$
          example: EUR
        frequency:
          type: string
          enum:
          - WEEKLY
          - BIWEEKLY
          - MONTHLY
          - QUARTERLY
          description: The execution frequency.
          example: WEEKLY
    SavingsPlan:
      type: object
      description: An automated recurring investment plan.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the savings plan.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_id:
          type: string
          format: uuid
          description: The account the savings plan belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        portfolio_id:
          type: string
          format: uuid
          description: The portfolio to invest into, if applicable.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        instrument_id:
          type: string
          format: uuid
          description: The instrument to invest into, if applicable.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        cash_amount:
          type: string
          description: The recurring investment amount as a decimal string.
          example: example-value
        currency:
          type: string
          description: The savings plan currency as an ISO 4217 code.
          pattern: ^[A-Z]{3}$
          example: EUR
        frequency:
          type: string
          enum:
          - WEEKLY
          - BIWEEKLY
          - MONTHLY
          - QUARTERLY
          description: How often the savings plan executes.
          example: WEEKLY
        status:
          type: string
          enum:
          - ACTIVE
          - PAUSED
          - CANCELLED
          description: The savings plan status.
          example: ACTIVE
        next_execution_date:
          type: string
          format: date
          description: The next scheduled execution date.
          example: '2025-03-15'
        created_at:
          type: string
          format: date-time
          description: When the savings plan was created.
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the savings plan 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
    SavingsPlanUpdate:
      type: object
      description: Request body for updating a savings plan.
      properties:
        cash_amount:
          type: string
          description: The updated investment amount.
          example: example-value
        frequency:
          type: string
          enum:
          - WEEKLY
          - BIWEEKLY
          - MONTHLY
          - QUARTERLY
          description: The updated execution frequency.
          example: WEEKLY
        status:
          type: string
          enum:
          - ACTIVE
          - PAUSED
          description: Activate or pause the savings plan.
          example: ACTIVE
  parameters:
    SavingsPlanId:
      name: savings_plan_id
      in: path
      required: true
      description: The unique identifier of the savings plan.
      schema:
        type: string
        format: uuid
    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
  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/