INFO

Diff for /documentation/guides/treasury/retrieving_treasury_reports.md

On this page, you can preview the modified document with the changes.
Note that the links within this diff are most likely broken because they are

  • relative to the original document or

  • point to another document that is not part of the changeset.


Go back to the summary


Retrieving settlement reports

In this section, we show you how to access the specific treasury reports via the Investments 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.

Get reports

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.

1. Get signed URL

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"
}

File naming convention

All settlement reports currently follow this naming convention:

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

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
* incoming-ca-ddmmyyyy.csv
* incoming-fee-ddmmyyyy.csv
* tax-treasury-ddmmyyyy.csv

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

Static reports endpoints

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

| Report | Static endpoint | |---|---| | Corporate action cash settlement | https://api.upvest.co/files/settlement_reports/incoming _ca_DDMMYYYY.csv | | Daily trades settlement - Buy | https://api.upvest.co/files/settlement_reports/buy_trading_DDMMYYYY.csv | | Daily trades settlement - Sell | https://api.upvest.co/files/settlement_reports/sell_trading_DDMMYYYY.csv | | Fee collection cash settlement | https://api.upvest.co/files/settlement_reports/incoming_fee_DDMMYYYY.csv |

2. Fetching the report

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

GET <PROVIDED “signed_url” PARAMETER>

WARNING

Please note that the signed URL is only valid for 15 minutes and only allows reads for the bucket.


Status code 400

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'

ExpiredToken

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).

Settlement advice webhooks

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

By retrieving this webhook, you therefore not only have the possibility to obtain data for reconciliation purposes, but you can also use the data contained therein as a basis for billing us.

Example webhook (outgoing)

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

The webhook provides you the following information:

ParameterExampleDescription
created_at2023-05-08T10:42:34.758ZThe date and time when the webhook was created (e.g., when Upvest issued a report to the client.)
directionOUTGOINGThe direction in relation to the client (incoming or outgoing).
filenametrading_buy_05082023.csvThe file name with which the client can retrieve the file from the /files endpoint.
report_date2023-05-08The date for which the report is created.
settlement_amount123.12The amount the client needs to transfer.
typeTRADINGThe settlement type (TRADING or CORPORATE ACTIONS) .

Example webhook (incoming)

{
  "created_at": "2023-06-16T10:42:34.758Z",
  "id": "157df2e0-944e-4f6a-abc5-6694115f9a02",
  "object": {
    "direction": "INCOMING",
    "filename": "incoming_fee_06162023.csv",
    "id": "731730f1-f4ce-40bf-a54f-198840437a27",
    "report_date": "2023-06-16",
    "settlement_amount": "1234.56",
    "type": "FEE"
  },
  "type": "TREASURY_REPORT.CREATED",
  "webhook_id": "39c1547d-447e-490f-b846-5e2832b2cea9"
}

The webhook provides you the following information:

ParameterExampleDescription
created_at2023-06-16T10:42:34.758ZThe date and time when the webhook was created (e.g., when Upvest issued a report to the client.)
directionINCOMINGThe direction in relation to the client (incoming or outgoing).
filenameincoming_fee_06162023.csvThe file name that the client can use to retrieve the file from the /files endpoint.
report_date2023-06-16The date for which the report is created.
settlement_amount1234.56The amount transfered to the client.
typeFEEThe settlement type (FEE, TRADING or CORPORATE ACTIONS) .

Was this page helpful?