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 have to fetch a signed URL, in the second step you can download the corresponding data via this URL.

On some occasions, we are required to issue multiple treasury reports on the same day. This includes, but is not limited to, the following scenarios:

• Corrections and updates for cancelled orders.
• Corrections for some corporate actions
• Corrections for one-off incidents
• Processing of delayed settlements

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.

Please ensure that you are set up to process both additional and amended treasury reports, if they occur.

You can download an example of both a real orders report and an updated report from our documentation assets repository.

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

The purpose of each endpoint corresponds to a specific report.

Call one of the 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 more detail here.

GET /files/settlement_reports/[fileName]

Example response

{
    "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",
    "updated_at": "2023-03-31T12:30:13Z"
}

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 following table lists the static endpoints for the different reports:

If branches are configured for your tenant, settlement reports are generated separately per branch.

Branches are assigned at user level with the branch_id set when creating a user or added later via a user data change request. The value for the branch ID is created by Upvest. You can work with your Launch Manager to configure branches for your tenant.

The report name then carries the branch name as a suffix:

The suffix equals the branch name in lowercase with spaces replaced by underscores. For example, a branch named "Client Netherlands Branch" produces a report named sell_trading_05062026_client_netherlands_branch.csv.

There is a separate file for each report type, per branch. This means a branch receives its own trades settlement report and its own corporate action cash settlement report.

Also, the buy/sell direction is determined independently for each branch. Different branches may receive reports for different directions on the same day.

The activity of users without an assigned branch is delivered in the standard reports without a branch suffix.

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

GET <PROVIDED “signed_url” PARAMETER>

If at the time of step 2 the signed url has already expired and the file has been deleted for security reasons, you will 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).

Through the Investment API, we provide a treasury reporting webhook that allows us to notify clients when we have a settlement report for them.

By accessing this webhook, clients receive information on the amounts of money to be transferred for settlement.

Example webhook (outgoing)

{
  "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_05082023.csv"
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

The webhook provides you the following information: