# Retrieving settlement reports

In this section, we show you how to access the specific treasury reports via the Investment API.

The process consists of two steps: first you fetch a signed URL, then you download the corresponding data via this URL.

## Multiple report delivery

On some occasions, we may issue multiple treasury reports of the same type on the same day. This can occur for several reasons, including but not limited to:

- Corrections and updates for cancelled orders.
- Corrections for some corporate actions.
- Corrections for one-off incidents.
- Processing of delayed settlements.
- Additional reports for the same object type, when more than one is generated for that type on the same day.


Additional treasury reports follow the same naming convention but include an underscore and an incremented number before the file's extension.

For example, if the first report is named `treasury-service buy_trading_11112025.csv` the next report appears as `treasury-service buy_trading_11112025_2.csv`.

The incremented filename only identifies which file to fetch. It does not indicate the reason for issuing a new report or how to process it relative to earlier reports.
We recommend relying on the details in the corresponding `TREASURY_REPORT.CREATED` webhook to determine how to process the file. Each additional report is a separate treasury operation and emits its own `TREASURY_REPORT.CREATED` and `TREASURY_REPORT.CONFIRMED` events (see [Settlement report webhooks](#settlement-report-webhooks)).

Ensure you are set up to process both additional and amended treasury reports, should they occur.

You can download an example of both a [real orders report](https://github.com/upvestco/documentation_assets/blob/main/treasury_report_samples/Treasury_correction_real_orders.csv) and an [updated report](https://github.com/upvestco/documentation_assets/blob/main/treasury_report_samples/Treasury_correction_updated.csv) from our documentation assets repository.

## Get reports

For the specific treasury reports you want to retrieve, proceed as described for the general data retrieval. Two steps are required, except that you now address dedicated static URLs in your request.

The purpose of each endpoint corresponds to a specific report.

### 1. Get signed URL

Call one of the [static reports endpoints](#static-reports-endpoints) listed in the table below to request a signed URL and file metadata.

The file sharing API requires a folder name (e.g., `settlement_reports`) and the requested file name (e.g., `incoming_ca_DDMMYYYY.csv`). The file names follow naming conventions, which are described in the [file naming convention](#file-naming-convention) section below.

**GET** `/files/settlement_reports/{file_name}`

**Example response**

```json
{
    "id": "d588e071-6e02-4ae6-a2b6-a5f08499633b",
    "created_at": "2024-03-04T08:24:18Z",
    "updated_at": "2024-03-14T11:18:39Z",
    "signed_url": "https://storage.googleapis.com/upvest-tooling-datasharing-service-ia-unstable-7263/48785b65bb0459547f9940db7678ef7601dc8826/test.txt?Expires=1680268944&GoogleAccessId=tooling-datasharing-service%40ia-unstable-7263.iam.gserviceaccount.com&Signature=AhbTgjMpKo%2BRB4T5pDEKI3Rw0kCWqyOPvkgKJHpvRKV%2FtSmWi2WvGPShBqc%2FvewnBSnFPeE%2BDrx5fdYSFbZ9WUo3n2BFUtFo%2FRIuh8zNyX5K7og58qO67PRlXKl%2B3HbHDyAx%2FgiOzmAbcIy0Au4LT%2F%2BYe2QMCVxxL7iM%2BPj5toANCyjZflTxM%2BdyZENhgiJ2j6q9uPsjBCP68PFHv%2BIwIIpsJhp9mTOIqH%2Bsbi%2FBckKHtYrrzCV1VzOpKi527y0%2FYUnmWDoV4ADXUmLuH73LlcoQ%2FOjBPvjR7PZCFT2yL4f9CBITfMzFacBDlX4jMZGZq%2BEbd04wxjMWQ%2B3N06zPeg%3D%3D",
    "file_name": "buy_trading_08052023.csv",
    "content_length": 919,
    "checksum": "709b190a108791217f62d839f85a7a997c2039cc29a737d59fd50454b85b2956"
}
```

#### File naming convention

All settlement reports currently follow this naming convention:

```
{direction}_{type}_{settlement_date}.csv
```

To comply with the SWIFT symbol policy, file names differ depending on the setup. If you want the file name in the payment reference, we switch the characters from `_` to `-`.

**Example file names**

- `buy-trading-ddmmyyyy.csv`
- `sell-trading-ddmmyyyy.csv`
- `zero-trading-ddmmyyyy.csv`
- `incoming-ca-ddmmyyyy.csv`
- `incoming-fee-ddmmyyyy.csv`
- `tax-treasury-ddmmyyyy.csv`
- `outgoing-transaction-fee-ddmmyyyy.csv`


This file name needs to be provided during step 1 of the described file sharing process.

The simplest way to obtain the exact file name is to read it from the `object.filename` field of the `TREASURY_REPORT.CREATED` webhook event (see [Settlement report webhooks](#settlement-report-webhooks)).

#### Static reports endpoints

The following table lists the static endpoints for the different reports:

### 2. Fetching the report

Use the signed URL returned in the response from step 1 to download the reporting files.

**GET** `<SIGNED_URL>`

The signed URL is valid for 15 minutes and only permits reads from the bucket.

## Status code `400`

If the signed URL has already expired at step 2 and the file has been deleted for security reasons, you receive status code `400` and an expired token error:

**Example 'Expired token'**

```
The provided token has expired.
`Request signature expired at: 2023-03-30T22:04:46+00:00`
```

In this case, request a signed URL again (see [step 1](#1-get-signed-url)).

## Settlement report webhooks

Through the Investment API, we provide [Treasury report events](/api/treasury-reports/treasury_report_event) that notify you about the lifecycle of each treasury operation. Two event types are emitted for every settlement report:

| **Event type** | **When it is emitted** | **Use it to** |
|  --- | --- | --- |
| `TREASURY_REPORT.CREATED` | A treasury settlement report has been generated and is available for download. | Learn the amount, direction and currency to be settled, and retrieve the report file via `object.filename`. |
| `TREASURY_REPORT.CONFIRMED` | The treasury operation covered by the report has been completed. | Confirm that the settlement payment has been processed and close the operation in your reconciliation. |


Both events carry the same report payload. The `object.id` and `object.filename` values are identical across the two events for the same treasury operation and can be used to correlate them. The top-level `id` and `created_at` fields differ, because they identify the individual event, not the report.

The `created_at` timestamp of the `TREASURY_REPORT.CONFIRMED` event marks when the treasury operation was completed. There is no separate completion field in the payload.

When branches are configured for the client, a separate treasury settlement report is generated per branch and each report emits its own set of events. In that case the report name carries the branch name as a suffix, for example `buy_trading_08052023_<branch_name>.csv`. Activity of users without an assigned branch is delivered in the standard report without a branch suffix.

**Example `TREASURY_REPORT.CREATED` event (outgoing)**

```json
{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2023-05-08T10:42:34.758Z",
  "type": "TREASURY_REPORT.CREATED",
  "object": {
    "id": "6e736b54-ed57-46ad-8620-0ef59ddd8e6d",
    "type": "TRADING",
    "currency": "EUR",
    "settlement_amount": "123.12",
    "report_date": "2023-05-08",
    "direction": "OUTGOING",
    "filename": "buy_trading_08052023.csv"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
```

**Example `TREASURY_REPORT.CONFIRMED` event for the same treasury operation**

Note that `object.id` and `object.filename` match the `TREASURY_REPORT.CREATED` event above, while `id` and `created_at` are specific to this event.

```json
{
  "id": "f3b1a9c2-7d44-4e21-9b6a-83c5de40f117",
  "created_at": "2023-05-08T14:22:11.123Z",
  "type": "TREASURY_REPORT.CONFIRMED",
  "object": {
    "id": "6e736b54-ed57-46ad-8620-0ef59ddd8e6d",
    "type": "TRADING",
    "currency": "EUR",
    "settlement_amount": "123.12",
    "report_date": "2023-05-08",
    "direction": "OUTGOING",
    "filename": "buy_trading_08052023.csv"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
```

The webhook provides you the following information:

| **Parameter** | **Example** | **Description** |
|  --- | --- | --- |
| `id` | `8962b496-8d42-4560-bfab-10490dd1a721` | Unique identifier of the webhook event. Differs between the `CREATED` and `CONFIRMED` events for the same report. |
| `created_at` | `2023-05-08T10:42:34.758Z` | Date and time when the event was created (RFC 3339, UTC). For `TREASURY_REPORT.CREATED` this is when Upvest issued the report; for `TREASURY_REPORT.CONFIRMED` this is when the treasury operation was completed. |
| `type` | `TREASURY_REPORT.CREATED` | The event type, either `TREASURY_REPORT.CREATED` or `TREASURY_REPORT.CONFIRMED`. |
| `object.id` | `6e736b54-ed57-46ad-8620-0ef59ddd8e6d` | Unique identifier of the treasury operation. Identical in both events; use it to correlate `TREASURY_REPORT.CREATED` with `TREASURY_REPORT.CONFIRMED`. |
| `object.type` | `TRADING` | The treasury operation type: `TRADING`, `CORPORATE_ACTION`, `FEE`, `TAX`, `TAX_ADJUSTMENT_RECEIVABLE`, `TAX_ADJUSTMENT_PAYABLE`, or `TRANSACTION_FEE`. |
| `object.currency` | `EUR` | The currency of the treasury payment, as an ISO 4217 three-letter code. |
| `object.settlement_amount` | `123.12` | The amount to be transferred for settlement. |
| `object.report_date` | `2023-05-08` | The date when the treasury report was created. |
| `object.direction` | `OUTGOING` | The direction of the treasury operation from the client's perspective: `INCOMING`, `OUTGOING`, or `NA` (when total buy equals total sell). |
| `object.filename` | `buy_trading_08052023.csv` | The file name used to retrieve the file from the `/files` endpoint. Carries a `_<branch_name>` suffix when branches are configured. |
| `webhook_id` | `9df39835-be87-4243-9018-f2500b39cee6` | Unique identifier of the webhook configuration that delivered the event. |