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

## Prerequisites

- **Authentication scopes** — `reports:read`, `transactions:read`
For more information, refer to [Authentication scopes](/products/byol/concepts/api_concepts/authentication/authentication_oauth#list-of-authentication-scopes).


Before retrieving user reports, ensure you have:

- **Webhook handler ready** — Set up a webhook endpoint to listen for report creation events.
  - Subscribe to [`REPORT.CREATED`](/products/byol/guides/reports/reports_webhooks) events.
For more information, refer to [Implementing webhooks](/products/byol/getting_started/implementing_webhooks).
- User account has already been created — reports are generated per user.
For more information, refer to [Creating users](/products/byol/guides/users#onboarding-a-user)


## 1. Using webhooks for real-time notifications

**Recommended: Use webhooks for new reports**

To check for new reports, set up a webhook listener for `REPORT.CREATED`. You will receive automatic notification when a new report is generated and is ready for download.

For more information, refer to [Report webhook events](/products/byol/guides/reports/reports_webhooks)

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`](/api/webhook-subscriptions/create_webhook)

**Example request body**

```json
{
  "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**

```json
{
  "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`](/api/reports/list_user_reports)

### Query parameters

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

| Parameter | Description | Example |
|  --- | --- | --- |
| `type` | Filters 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` |
| `instrument` | Filters the list so that it only contains reports on a specific instrument. | `uuid:ebabcf4d-61c3-4942-875c-e265a7c2d062` |
| `start_date` | Returns reports created from this date and including this date (UTC). | `2022-08-12` |
| `end_date` | Returns the reports created up to this date (UTC). | `2023-12-12` |
| `sort` | Field of the resource to be sorted by. Possible values: `id`, `type`, `created_at` | `id` |
| `order` | Sort order of the result list when using the `sort` parameter. Supports `ASC` for ascending or `DESC` for descending sort order. | `ASC` |
| `limit` | Specifies the maximum number of items returned. | `100` |
| `offset` | Specifies where in the list of results to start when returning items for a particular query. | `0` |


### Report types

| Report type | Description |
|  --- | --- |
| `ACCOUNT_OPENING` | Securities account opening. |
| `ACCOUNT_CLOSING` | Securities account closure. |
| `AD_HOC_ACCOUNT_STATEMENT` | Temporary or one-time statement of account. |
| `ANNUAL_INCOME_STATEMENT` | Annual tax income statement (*Erträgnisaufstellung*) |
| `ANNUAL_TAX_STATEMENT` | The annual tax report. |
| `BANK_ACCOUNT_CONNECTED` | The connected reference bank account. |
| `BUY_ORDER` | Buy order. |
| `CANCELLED_ORDER` | Cancelled buy or sell order (which has not yet been executed, the user or the trading venue has cancelled). |
| `CORPORATE_ACTION_CASH_TRANSACTION` | The cash transaction document (after corporate action). |
| `CORPORATE_ACTION_SECURITY_TRANSACTION` | The security transaction document (after corporate action). |
| `DIRECT_DEBIT_MANDATE` | Creation of a SEPA direct debit mandate. |
| `EX_POST_COST` | The ex-post cost report. |
| `GENERIC_COMMUNICATION` | Generic communication. |
| `INCOME_DISTRIBUTION` | Income distribution report. |
| `MONTHLY_BILLING_STATEMENT` | Monthly billing activities statement. |
| `QUARTERLY_ACCOUNT_STATEMENT` | The quarterly account statement. |
| `REVOKED_ORDER` | Revoked buy or sell order ("Storno"). |
| `SECURITIES_TRANSFER_INCOMING` | Securities are being transferred in. |
| `SECURITIES_TRANSFER_OUTGOING` | Securities are being transferred out. |
| `SELL_ORDER` | Sell order. |
| `TAX_PAYMENT` | Tax payment document. |
| `TAX_PREPAYMENT_DE` | German tax prepayment ("Vorabpauschale"). |
| `TAX_PREPAYMENT_DE_CANCELLATION` | German tax prepayment ("Vorabpauschale") cancelled due to unsuccessful tax collection. |
| `TAX_REFUND` | Tax refund document (after tax optimisation). |
| `FRENCH_IFU` | French tax statement (Imprimé fiscal unique). |


**Example response**

```json
{
  "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:

| Parameter | Description | Example |
|  --- | --- | --- |
| `id` | The report ID. | `b96b1ee7-d491-43eb-b5e4-4833af9c9c2f` |
| `created_at` | The date when the report was created. | `2023-08-24T14:15:22Z` |
| `user_id` | The ID of the user for whom the report was created. | `d1a4be99-8bb6-4e78-b897-8168f6823ab5` |
| `type` | The report type. | `BUY_ORDER` |
| `substituted_report_id` | This 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'](/products/byol/guides/reports/user_reports_types#substitue-report) above. | `null` |


## 3. Downloading a report

To download an individual report, perform the following operation:

**GET** [`reports/{report_id}`](/api/reports/retrieve_report)

| Path parameter | Description |
|  --- | --- |
| `report_id` | **Required**: Specify the ID of the report that you want to retrieve. |


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