User reporting

After reading this guide, you will have a clear understanding of what user reports are and why they are important. Furthermore, you will have all the knowledge necessary to implement user reporting.

How user reporting works

As a regulated securities trading bank, Upvest provides access to all legally required user reports via a simple API interface. In this context, “user reports” is a broad term that describes all reports, documents, or statements that need to be produced during the investment lifecycle. Examples are annual tax statements, order confirmations, and dividend distribution receipts.

The Investment API user reports service feature provides your end users with important information about their investments, accounts, and legal requirements. User reports are generated by Upvest's background processes for each individual user. The reports can be queried but not updated or removed.

The report generation process is invoked by specific, pre-defined trigger events that typically result from other business processes or interactions with other endpoints of the Investment API. For example, when one of your users places an order, the corresponding order execution and resulting transaction is a trigger event that initiates the creation of a buy order report.

Implementing user reporting

Prerequisites

Since reports are created per user, the minimum requirement for querying reports is that you have created a user.

To access all required user reports, you can either subscribe to webhooks or use the list and retrieve endpoints of the Investment API. Both approaches allow you to access all reports of any user at any time, so that you can meet your legal requirements and deliver an optimal user experience.

Utilizing webhooks to be notified real time

You can subscribe to our webhook service to receive instant notifications about noteworthy events. For example, upon completion of a report generation for one of your users, Upvest will send a webhook to your registered URL notifying your systems that a new report is available and ready for download. This setup allows you to feed information about your user's investments into their inboxes in near real time.

Subscribing to webhooks

Unless you have not already subscribed to ALL webhook types, subscribe to the webhook type REPORT by sending POST /webhooks with the following request body:

Example request

{
  "title": "User report webhook",
  "url": "https://tenant.tld/webhooks/users",
  "type": [
    "REPORT"
  ],
  "config": {
    "delay": "5s",
    "max_package_size": 10240
  }
}

If you have subscribed to a webhook of the type REPORT, you will receive a webhook message every time a report is created for one of your users.

Example webhook message

{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "REPORT.CREATED",
  "object": {
    "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
    "created_at": "2020-08-24T14:15:22Z",
    "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5",
    "type": "BUY_ORDER",
    "substituted_report_id": null,
    "data": {
      "account": {
          "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8"
      }
  }
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Downloading reports

You can download reports with GET /reports/{report_id}.

Retrieving user reports via endpoints

Alternatively, you can use the Investment API to list all reports for a specific user at any time. Calling the /reports endpoint gives you access to the metadata of all individual reports, and allows you to filter the report list using query parameters. This way, you can retrieve a specific range of reports, e.g., only buy order statements, tax-related reports, or all user reports generated within a given time period.

Viewing reports

To list all reports of specific user send GET /users/{user_id}/reports. In the response, you will receive the following data for each report in the selected list:

Example response

{
    "meta": {
        "offset": 0,
        "limit": 100,
        "count": 1,
        "total_count": 1,
        "sort": "id",
        "order": "ASC"
    },
    "data": [
        {
            "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
            "created_at": "2020-08-24T14:15:22Z",
            "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5",
            "type": "BUY_ORDER",
            "substituted_report_id": null,
            "data": {
                "account": {
                    "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8"
                }
            }
        }
    ]
}

Substitute reports

In the examples on this page you can see a substituted_report_id field as part of the webhook messages. This field is used to establish a link between two related reports. If populated, this field contains the id of a previously generated report.

An example where this field is populated is the case of a mistrade, i.e. when an user order has been wrongly executed by the respective exchange. Mistrades are only known after the fact, meaning after the order has been marked as fully executed. As such the user will already have received a buy or sell order report. Once the mistrade has been reversed by the exchange, our system will create a REVOKED_ORDER report to inform you and the user about the happening. The webhook that is sent for this new revoked order report will contain the report_id of the buy or sell report that was previously created.

Query parameters for report types

In the request, it is possible to filter the list of report types using query parameters and thus narrow down the result. You can filter for the following report types with the type query parameter:

Report type	Description
BUY_ORDER	Buy order
SELL_ORDER	Sell order
INCOME_DISTRIBUTION	Income dostribution report
GENERAL_MEETING_NOTIFICATION	General meeting notification
FUND_COMMUNICATION	Generic fund communication
TAX_REFUND	Tax refund document (after tax optimisation)
CANCELLED_ORDER	Cancelled buy or sell order (not yet executed, the user or the trading venue cancelled).
REVOKED_ORDER	Revoked buy or sell order ("Storno")
ACCOUNT_OPENING	Securities account opening.
ACCOUNT_CLOSING	Securities account closure.
DIRECT_DEBIT_MANDATE	Creation of SEPA direct debit mandate.
ANNUAL_TAX_STATEMENT	The annual tax reporting.
ANNUAL_ACCOUNT_STATEMENT	The annual income statement ("Ertragnisaufstellung").
GENERIC_COMMUNICATION	Generic communication.
BANK_ACCOUNT_CONNECTED	The connected reference bank account.

Downloading reports

You can download the individual reports by calling GET /reports/{report_id}. To call a specific report, use the appropriate report_id extracted from the list reports response.