# Get a Portfolio Valuation

import { Stepper } from "zudoku/ui/Stepper";

The Transact API gives your application the ability to retrieve Transact valuations as of the end of the previous business day.

:::note

If you are currently connected to the legacy TRDS Valuation endpoint, also see [Migrating from TRDS - Valuation](migrating-from-trds.md#valuation)
taking note of the OAuth requirement, and [Key differences from TRDS](#key-differences-from-trds) below.

:::

## Scenario

An adviser firm or adviser network using your application wishes to retrieve bulk valuation data, with wrapper and investment details,
for all Transact investor portfolios managed by them, or for specific firms, advisers or investors.

Your application wishes to record the reported holdings for Transact wrappers against the equivalent representation in your system (often labelled as "plans", "accounts" or "policies").

## Workflow

A theoretical workflow might consist of these steps:

<Stepper>

1. **Your application requests valuation data**

    Within your application, a scheduled task runs in the morning to retrieve bulk data for the firm or network,
    or perhaps the adviser initiates an ad-hoc request themselves for a specific portfolio.

    Your application calls the [Get valuations](/api/valuations#get-valuations) endpoint.

2. **Your application reconciles valuations with recorded plans/accounts/policies**

    With the response from the API call, your application matches the returned investor Transact numbers and Transact Wrapper references (eg 'IH55500001')
    to records already stored within your application.

    If a client cannot be matched by Transact number, you may choose to retrieve personal data related to the Transact *portfolios*
    by calling the [Get investor portfolios](/api/investors#get-investor-portfolios) endpoint. This retrieves
    some personal data (for example data of birth, NINO) that can be used to match the Transact portfolio to the client recorded in your application.

3. **Application records are added/updated**

    Your application may create any missing account/plan/policy records automatically, or ask the adviser to manually resolve non matches.

    The valuation data is then stored by your application against the matched plans/accounts/policies.

    Investor Transact numbers and Transact Wrapper reference values are stored within the application for subsequent matching purposes.

</Stepper>

## Example implementation

:::note

This guide assumes you have already followed the [Getting Started](../getting-started/overview.md) guide to register
with Transact, and have implemented OAuth authentication. For this workflow, you'll need an access token for an adviser firm or network
with the following scopes.

- `valuation.read`
- `investor-personal.read`  (needed if you wish to retrieve investor personal data for matching purposes)

:::

### Retrieving valuation data

Call the [Get valuations](/api/valuations#get-valuations) endpoint (`GET /valuations`).

This endpoint retrieves [paginated](../advanced/pagination.md) valuation data.

The returned JSON looks something like the below:

```json title="Response body"
{
  "items": [
    {
      "id": "333333331",
      "adviser_id": "222222221",
      "firm_id": "111111111",
      "wrappers": [
        {
          "id": "IH00000001",
          "type": "GENERAL_INVESTMENT_ACCOUNT",
          "name": "Savings for Jennifer",
          "status": "OPEN",
          "opening_date": "2024-01-31",
          "closing_date": null,
          "closed_date": null,
          "holdings": [
            {
              "investment_id": "IP00000002",
              "investment_name": "Cash",
              "isin": "",
              "is_cash": true,
              "price": 1.0000,
              "price_date": "2000-03-15",
              "units": 100.9500
            },
            {
              "investment_id": "IP12345678",
              "investment_name": "Investments Ltd",
              "isin": "GB1234567890",
              "is_cash": false,
              "price": 1.1234,
              "price_date": "2025-01-30",
              "units": 200.1234
            }
          ]
        }
      ]
    }
  ]
  // ... page navigation data ...
}
```

### Retrieving personal data for reconciliation

If, after retrieving the valuation data, the application cannot recognise a wrapper using a previously recorded wrapper reference (above example 'IH00000001'), take note of the associated investor's Transact number from the response (above example '333333331').

If your application can directly match the investor's Transact number to a client record, that's great!

If not, read on.

Call the [Get investor portfolios](/api/investors#get-investor-portfolios) endpoint (`GET /investor-portfolios`).

This endpoint retrieves [paginated](../advanced/pagination.md) data containing open investor portfolios and underlying personal data.

You can filter by:

- the unrecognised investors, using the `investor_portfolio_ids` parameter
- advisers, using the `adviser_ids` parameter
- firms, using the `firm_ids` parameter.

Simply omit these parameters to retrieve all investors.

The returned JSON looks something like the below:


```json title="Response body"
{
  "items": [
    {
      "id": "333333331",
      "adviser_id": "222222221",
      "firm_id": "111111111",
      "name": "Miggins, Jennifer",
      "type": "INDIVIDUAL",
      "individuals": [
        {
          "id": "IDN123456789012",
          "surname": "Miggins",
          "given_names": "Jennifer",
          "date_of_birth": "2000-12-25",
          "nino": "QQ123456C"
        }
      ],
      "corporation": null,
      "trust": null
    }
  ]
  // ... page navigation data ...
}
```
Using the personal data returned, your application can match the unrecognised Transact investor portfolio to the application's client record.

We recommend storing investor Transact numbers and Wrapper references within your application data, in order to establish a direct link and to
limit the need for reconciliation.

## Key differences from TRDS

If you are currently connected to the **deprecated** TRDS Valuation endpoint, it is worth noting these key differences:

- Implementing OAuth is required.
- Responses are JSON-encoded and have a hierarchical structure.
- Responses are paginated.
- There is support for adviser networks.
- Wrappers without holdings are included, allowing easier identification of new wrappers that are yet to receive a contribution.
- Wrapper status information is included, improving visibility of wrapper activity such as new and closed wrapper events.
- Wrappers don't immediately disappear when they are closed, again improving visibility of that event.
- Investor personal data is no longer available via the endpoint itself, but is available via the separate [Get investor portfolios](/api/investors#get-investor-portfolios) endpoint.