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:

Report types

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:

3. Downloading a report

To download an individual report, perform the following operation:

GET reports/{report_id}

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