> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get user investment details

> Return portfolio-specific performance metrics for a user-held investment product.

Retrieve personalised portfolio metrics for the authenticated user and the specified ISIN. The
portfolio is validated to ensure the user currently holds the asset; otherwise a `400 Bad Request`
error is returned.

### Authentication & headers

<ParamField header="Authorization" type="string" required>
  Bearer token issued by Auth0. Format: `Bearer YOUR_ACCESS_TOKEN` with the `read:users` scope.
</ParamField>

<ParamField header="x-user-id" type="string" required>
  24-character MongoDB identifier of the authenticated user. Required to resolve the correct portfolio
  and currency formatting.
</ParamField>

### Path parameters

<ParamField path="isin" type="string" required>
  ISIN of the investment product to inspect.
</ParamField>

### Example request

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.wealthyhood.com/investment-products/IE00B4L5Y983/investment-details' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'x-user-id: 64f0c51e7fb3fc001234abcd'
  ```
</RequestExample>

### Example response

<ResponseExample>
  ```json Success theme={null}
  {
    "currentValue": "£1,254.18",
    "portfolioAllocation": "12.4%",
    "numberOfShares": "15.2500",
    "performanceValue": "+£154.18",
    "performancePercentage": "Up by 14.0%",
    "isPerformancePositive": true,
    "averagePricePerShare": "$72.50",
    "totalDividends": "£18.40"
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="currentValue" type="string" required>
  Holding valuation formatted in the user's base currency.
</ResponseField>

<ResponseField name="portfolioAllocation" type="string" required>
  Portfolio share of the asset, returned as a localised percentage string.
</ResponseField>

<ResponseField name="numberOfShares" type="string" required>
  Quantity held, formatted to up to four decimal places.
</ResponseField>

<ResponseField name="performanceValue" type="string" required>
  Absolute performance with sign and currency formatting.
</ResponseField>

<ResponseField name="performancePercentage" type="string" required>
  Localised summary of percentage performance (e.g. `Up by 14.0%`).
</ResponseField>

<ResponseField name="isPerformancePositive" type="boolean" required>
  Indicates whether the holding performance is positive.
</ResponseField>

<ResponseField name="averagePricePerShare" type="string" required>
  Average acquisition price in the asset's traded currency.
</ResponseField>

<ResponseField name="totalDividends" type="string" required>
  Total dividend cashflow received for the asset, formatted in the user's currency.
</ResponseField>


## OpenAPI

````yaml GET /investment-products/{isin}/investment-details
openapi: 3.0.3
info:
  title: Wealthyhood Investment Products API
  version: 1.0.0
  description: >
    Machine-to-machine endpoints that expose the Wealthyhood asset universe,
    fundamentals, and

    user-specific portfolio context.


    All requests require an Auth0-issued bearer token with the `read:users`
    scope, and must 

    include the `x-user-id` header so the retail user context can be resolved.
servers:
  - url: https://{host}
    variables:
      host:
        default: api.wealthyhood.com
        description: Wealthyhood API host.
security:
  - bearerAuth: []
tags:
  - name: Investment Products
    description: >-
      Listed instruments available to Wealthyhood investors together with
      client-specific insights.
paths:
  /investment-products/{isin}/investment-details:
    get:
      tags:
        - Investment Products
      summary: Get user investment details for an asset
      description: >
        Return portfolio-specific metrics for the authenticated user, including
        current value, allocation,

        and performance indicators for the requested ISIN. The user must hold
        the asset; otherwise a

        `400 Bad Request` is returned.
      parameters:
        - $ref: '#/components/parameters/ExternalUserId'
        - $ref: '#/components/parameters/Isin'
      responses:
        '200':
          description: User-centric performance metrics for the asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInvestmentDetails'
              examples:
                userInvestment:
                  summary: Investment details for a held ETF
                  value:
                    currentValue: £1,254.18
                    portfolioAllocation: 12.4%
                    numberOfShares: '15.2500'
                    performanceValue: +£154.18
                    performancePercentage: Up by 14.0%
                    isPerformancePositive: true
                    averagePricePerShare: $72.50
                    totalDividends: £18.40
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  parameters:
    ExternalUserId:
      name: x-user-id
      in: header
      required: true
      description: >-
        MongoDB identifier of the Wealthyhood user whose subscription context
        should be applied.
      schema:
        type: string
        pattern: ^[a-f0-9]{24}$
    Isin:
      name: isin
      in: path
      required: true
      description: ISIN of the investment product to retrieve.
      schema:
        type: string
        pattern: ^[A-Z0-9]{12}$
  schemas:
    UserInvestmentDetails:
      type: object
      properties:
        currentValue:
          type: string
          description: Holding valuation formatted in the user's base currency.
        performanceValue:
          type: string
          description: Absolute performance formatted with sign.
        performancePercentage:
          type: string
          description: Localised percentage summarising performance direction.
        numberOfShares:
          type: string
        portfolioAllocation:
          type: string
        isPerformancePositive:
          type: boolean
        averagePricePerShare:
          type: string
        totalDividends:
          type: string
      required:
        - currentValue
        - performanceValue
        - performancePercentage
        - numberOfShares
        - portfolioAllocation
        - isPerformancePositive
        - averagePricePerShare
        - totalDividends
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
        error:
          type: object
          properties:
            message:
              type: string
            description:
              type: string
              nullable: true
        responseId:
          type: string
          format: uuid
      required:
        - status
        - error
  responses:
    BadRequestError:
      description: Validation failure or business rule violation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 400
            error:
              message: Unknown asset ISIN
            responseId: 6d86bcab-9c21-45da-9b9d-820d598e1f3b
    UnauthorizedError:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 401
            error:
              message: User not found
            responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a
    ForbiddenError:
      description: Authenticated user cannot access the requested resource or lacks scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 403
            error:
              message: Access forbidden for portfolio
            responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76
    NotFoundError:
      description: Investment product was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 404
            error:
              message: Product not found
            responseId: 0c8d8376-43db-4318-8ad4-0452bc0ce450
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Auth0-issued access token that includes the `read:users` scope.

````