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.
As part of the Investment API, the report service serves two main objectives:
- Ensure that all involved parties adhere to the legal and regulatory requirements
- Elevate the end-user experience by providing meaningful and easy-to-access documentation related to a user's investments
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}
.
It is important that you set the accept header to ‘application/pdf’ when calling this endpoint in order to return the PDF report in binary format.
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.
To issue the reports as PDF, set application/pdf
in the accept header.
Was this page helpful?