> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openregister.de/llms.txt
> Use this file to discover all available pages before exploring further.

# List Monitors

## List monitors

Returns all monitors created for the current API user.

**Cost:** 0 credits

<Note>
  See the [Monitoring guide](/guide/monitoring) for a full overview of how monitoring works, including webhook setup and preference options.
</Note>

### Response

The response contains an `items` array. Each item represents one active or disabled monitor and includes:

| Field         | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| `entity_id`   | string  | The company register ID or person UUID being monitored |
| `entity_type` | string  | `company` or `person`                                  |
| `preferences` | array   | The data categories this monitor is watching           |
| `disabled`    | boolean | Whether the monitor has been disabled by the system    |

### The `disabled` flag

A monitor is marked `disabled: true` when your account is downgraded to a plan that no longer includes monitoring access. Disabled monitors are preserved so you do not lose your configuration, but they stop delivering notifications.

Monitors are **not** automatically re-enabled when you upgrade again — this is intentional to prevent unexpected billing. To re-enable a disabled monitor, contact the team at [founders@openregister.de](mailto:founders@openregister.de).

Use the list endpoint to check for disabled monitors after any plan change so you can act before missing notifications.

### Use Cases

**Audit active subscriptions** — Retrieve the full list of entities you are currently watching to verify coverage, identify gaps, or reconcile against your internal records.

**Detect disabled monitors** — Filter the response for `disabled: true` items to find monitors that have stopped delivering notifications due to a plan downgrade. Contact [founders@openregister.de](mailto:founders@openregister.de) to get them re-enabled.

**Reconcile with your database** — Periodically compare the list of monitors against your own data to identify entities that should no longer be monitored and clean them up with the delete endpoint.


## OpenAPI

````yaml GET /v1/monitor
openapi: 3.1.0
info:
  title: OpenRegister API
  version: 2.0.0
  description: >
    API for accessing comprehensive company data from official registers.

    This API provides access to company information, shareholder data, financial
    reports, and contact details.
servers:
  - url: https://api.openregister.de
    description: Production
security:
  - BearerAuth: []
paths:
  /v1/monitor:
    get:
      tags:
        - v1
      summary: List webhook monitor items
      operationId: listWebhookMonitorItems
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookMonitorItemsResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Openregister from 'openregister';

            const client = new Openregister({
              apiKey: process.env['OPENREGISTER_API_KEY'], // This is the default and can be omitted
            });

            const monitors = await client.monitor.list();

            console.log(monitors.items);
        - lang: Python
          source: |-
            import os
            from openregister import Openregister

            client = Openregister(
                api_key=os.environ.get("OPENREGISTER_API_KEY"),  # This is the default and can be omitted
            )
            monitors = client.monitor.list()
            print(monitors.items)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/oregister/openregister-go\"\n\t\"github.com/oregister/openregister-go/option\"\n)\n\nfunc main() {\n\tclient := openregister.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmonitors, err := client.Monitor.List(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", monitors.Items)\n}\n"
        - lang: CLI
          source: |-
            openregister monitor list \
              --api-key 'My API Key'
components:
  schemas:
    WebhookMonitorItemsResponse:
      type: object
      properties:
        items:
          type: array
          description: |
            List of webhook monitor items.
          items:
            $ref: '#/components/schemas/WebhookMonitorItem'
      required:
        - items
    WebhookMonitorItem:
      type: object
      properties:
        entity_type:
          $ref: '#/components/schemas/WebhookMonitorEntityType'
        entity_id:
          type: string
          description: |
            For `company` this is the register ID (e.g. `DE-HRB-F1103-267645`).
            For `person` this is the person UUID.
        preferences:
          description: >
            Preferences for the entity to monitor.

            Use `WebhookMonitorCompanyPreference` values when `entity_type` is
            `company`,

            and `WebhookMonitorPersonPreference` values when `entity_type` is
            `person`.
          type: array
          items:
            $ref: '#/components/schemas/WebhookMonitorPreference'
        disabled:
          type: boolean
          description: Whether the monitor item is disabled.
      required:
        - entity_type
        - entity_id
        - preferences
        - disabled
    WebhookMonitorEntityType:
      type: string
      description: |
        Type of the entity to monitor.
      enum:
        - company
        - person
    WebhookMonitorPreference:
      type: string
      description: >
        All possible monitor preference values across all entity types.


        Which values are valid depends on `entity_type`:


        **Company** (`entity_type: company`)

        | Value | Description |

        |---|---|

        | `basic` | Core firmographic data (name, address, legal form, status) |

        | `representation` | Directors, officers, and authorised signatories |

        | `financials` | Annual accounts and financial statements |

        | `documents` | Filed documents and publications |

        | `ownership` | Direct owners of the company |

        | `holdings` | Companies in which this company holds a stake |


        **Person** (`entity_type: person`)

        | Value | Description |

        |---|---|

        | `management_positions` | Board and management roles the person holds |

        | `holdings` | Companies in which this person holds a stake |


        Passing a value that does not apply to the given `entity_type` will
        result

        in a validation error.
      enum:
        - basic
        - representation
        - financials
        - documents
        - ownership
        - holdings
        - management_positions
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API Key Authentication
        Provide your API key as a Bearer token in the Authorization header.

````