openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers User Identifiers 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: User Identifiers
  description: Manage external identifiers associated with users.
paths:
  /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
components:
  schemas:
    UserIdentifierUpdate:
      type: object
      description: Request body for updating a user identifier.
      properties:
        value:
          type: string
          description: The updated identifier value.
          example: example-value
    UserIdentifierCreate:
      type: object
      description: Request body for creating a user identifier.
      required:
      - type
      - value
      properties:
        type:
          type: string
          description: The type of external identifier.
          example: standard
        value:
          type: string
          description: The identifier value.
          example: example-value
    UserIdentifier:
      type: object
      description: An external identifier associated with a user.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          description: The type of external identifier.
          example: standard
        value:
          type: string
          description: The identifier value.
          example: example-value
        created_at:
          type: string
          format: date-time
          description: When the identifier was created.
          example: '2025-03-15T14:30:00Z'
    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
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      description: The unique identifier of the user.
      schema:
        type: string
        format: uuid
    IdentifierId:
      name: identifier_id
      in: path
      required: true
      description: The unique identifier of the user identifier.
      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/