Accessing end user reports

To access all required user reports, you can either subscribe to webhooks or use the list and retrieval endpoints of the Investment API. With both approaches, you can access all reports of any user at any time so that you can fulfil your legal requirements and provide an optimal user experience.

Requirements

As reports are created per user, the minimum requirement for requesting reports is that the relevant user account has already been created.

1. Using webhooks for real-time notifications

You can subscribe to our webhook service to receive instant notifications of notable events.

For example, when a report is created for one of your users, Upvest will send a webhook to your registered URL to inform you that a new report is available and can be downloaded. In this way, you can provide your users' inboxes with near real-time information about their investments.

Subscribing to webhooks

If you have not already subscribed to ALL webhook types, subscribe to the REPORT webhook type by sending

POST /webhooks

Example request body

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

Once you have subscribed to this webhook, you will receive a message each 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": "CORPORATE_ACTION_CASH_TRANSACTION",
    "substituted_report_id": null,
    "data": {
      "account": {
          "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8"
      },
      "references": [
        {
          "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
          "type": "CORPORATE_ACTION_TRANSACTION_ID"
        }
      ]
  }
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

2. Retrieving user reports via the API

Alternatively, you can also use the Investment API to list all reports for a specific user.

Since calling the /reports endpoint also gives you access to the metadata of all individual reports, it is possible to filter the results list more precisely using this metadata in the form of query parameters.

In this way, you can, for example, limit the results to only purchase order statements, tax-related reports or all user reports that were created within a certain time period.

To list all reports of specific user send

GET /users/{user_id}/reports

Query parameters

You can narrow down the results list using the following query parameters:

ParameterDescriptionExample
typeFilters the list to display only reports of a certain type (e.g. only purchase order confirmations).
You can find the list of possible types below.
BUY_ORDER
instrumentFilters the list so that it only contains reports on a specific instrument.uuid:ebabcf4d-61c3-4942-875c-e265a7c2d062
start_dateReturns reports created from this date and including this date (UTC).2022-08-12
end_dateReturns the reports created up to this date (UTC).2023-12-12
sortField of the resource to be sorted by.
Possible values: id, type, created_at
id

Report types

Expand list of report types
Report typeDescription
ACCOUNT_OPENINGSecurities account opening.
ACCOUNT_CLOSINGSecurities account closure.
AD_HOC_ACCOUNT_STATEMENTTemporary or one-time statment of account.
ANNUAL_ACCOUNT_STATEMENTAnnual statement of account.
ANNUAL_INCOME_STATEMENTThe annual income statement ("Ertragnisaufstellung").
ANNUAL_TAX_STATEMENTThe annual tax report.
BANK_ACCOUNT_CONNECTEDThe connected reference bank account.
BUY_ORDERBuy order.
CANCELLED_ORDERCancelled buy or sell order (which has not yet been executed, the user or the trading venue has cancelled).
CORPORATE_ACTION_CASH_TRANSACTIONThe cash transaction document (after corporate action).
CORPORATE_ACTION_SECURITY_TRANSACTIONThe security transaction document (after corporate action).
DIRECT_DEBIT_MANDATECreation of a SEPA direct debit mandate.
EX_POST_COSTThe export cost report.
FUND_COMMUNICATIONGeneric fund communication.
GENERAL_MEETING_NOTIFICATIONThe general meeting notification.
GENERIC_COMMUNICATIONGeneric communication.
INCOME_DISTRIBUTIONIncome distribution report.
INCOME_REINVESTMENTThe reinvestment billing report (accumulating funds).
QUARTERLY_AACOUNT_STATEMENTThe quarterly account statement.
REVOKED_ORDERRevoked buy or sell order ("Storno").
SECURITIES_TRANSFER_INCOMINGSecurities are being transferred in.
SECURITIES_TRANSFER_OUTGOINGSecurities are being transferred out.
SELL_ORDERSell order.
TAX_EXEMPTION_CREATIONAn exemption order ("Freistellungsauftrag") has been created.
TAX_OPTIMISATIONTax optimisation report.
TAX_PREPAYMENT_DEGerman tax prepayment ("Vorabpauschale").
TAX_REFUNDTax refund document (after tax optimisation).

Example response

{
  "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": "CORPORATE_ACTION_CASH_TRANSACTION",
    "substituted_report_id": null,
    "data": {
      "account": {
          "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8"
      },
      "references": [
        {
          "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
          "type": "CORPORATE_ACTION_TRANSACTION_ID"
        }
      ]
  }
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

In the response, you will receive the following data for each report in the selected list:

ParameterDescriptionExample
idThe report ID.b96b1ee7-d491-43eb-b5e4-4833af9c9c2f
created_atThe date when the report was created.2023-08-24T14:15:22Z
user_idThe ID of the user for whom the report was created.d1a4be99-8bb6-4e78-b897-8168f6823ab5
typeThe report type.BUY_ORDER
substituted_report_idThis field is used to create a link between two related reports. If it is populated, this field contains the ID of a previously created report.
See 'Substitute report' above.
null

3. Downloading a report

To download an individual report, perform the following operation:

GET reports/{report_id}

Path parameterDescription
report_idRequired: Specify the ID of the report that you want to retrieve.
TIPP

To specify the desired output format of the reports (PDF or JSON), set application/pdf or application/json in the accept-header.


Was this page helpful?