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

# Create Monitor

## Create a monitor

Create a monitor to receive webhook notifications when a company or person is updated.

**Cost:** 25 credits

<Note>
  Before creating monitors, you must configure a webhook URL in your [OpenRegister dashboard](https://openregister.de/keys). See the [Monitoring guide](/guide/monitoring) for a full overview of how monitoring works.
</Note>

### Entity ID

The `entity_id` format depends on the `entity_type`:

* **Company** — use the register ID, e.g. `DE-HRB-F1103-267645`. You can find this on the company page or via the search endpoints.
* **Person** — use the person UUID returned by the person search or person endpoint.

### Preferences

Preferences control which data categories trigger a webhook notification. You must provide at least one preference. All values must correspond to the given `entity_type` — mixing preferences across entity types returns a `400 Bad Request`.

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

| Value            | What triggers a notification                                             |
| ---------------- | ------------------------------------------------------------------------ |
| `basic`          | Core firmographic data — name, registered address, legal form, or status |
| `representation` | Directors, officers, managing partners, or authorised signatories        |
| `financials`     | Annual accounts or financial statements filed                            |
| `documents`      | New documents or publications filed with the register                    |
| `ownership`      | Direct owners (shareholders) of the company                              |
| `holdings`       | Companies in which this company holds a stake                            |

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

| Value                  | What triggers a notification                                  |
| ---------------------- | ------------------------------------------------------------- |
| `management_positions` | Board or management roles the person holds across any company |
| `holdings`             | Companies in which this person holds a stake                  |

### Use Cases

**Compliance monitoring** — Subscribe to `basic`, `representation` and `ownership` changes on counterparties or customers. Receive alerts on legal form conversions, address moves, or management changes as soon as they appear in the register.

**Ownership change alerts** — Use the `ownership` and `holdings` preferences to detect when a company's shareholder structure changes, keeping your KYC data current without manual re-checks.

**Financial filing alerts** — Monitor the `financials` and `documents` preferences to be notified the moment new annual accounts or register publications are available, enabling automated document retrieval and archiving workflows.

**Due diligence pipelines** — Add a monitor when onboarding a new counterparty. Receive ongoing notifications for the duration of the relationship and remove the monitor when the relationship ends.


## OpenAPI

````yaml POST /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:
    post:
      tags:
        - v1
      summary: Create webhook monitor
      operationId: createWebhookMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMonitorItemRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookMonitorItem'
        '400':
          description: Bad Request
        '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 monitor = await client.monitor.create({
              entity_id: 'entity_id',
              entity_type: 'company',
              preferences: ['basic'],
            });

            console.log(monitor.entity_id);
        - 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
            )
            monitor = client.monitor.create(
                entity_id="entity_id",
                entity_type="company",
                preferences=["basic"],
            )
            print(monitor.entity_id)
        - 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\tmonitor, err := client.Monitor.New(context.TODO(), openregister.MonitorNewParams{\n\t\tEntityID:    \"entity_id\",\n\t\tEntityType:  openregister.MonitorNewParamsEntityTypeCompany,\n\t\tPreferences: []string{\"basic\"},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", monitor.EntityID)\n}\n"
        - lang: CLI
          source: |-
            openregister monitor create \
              --api-key 'My API Key' \
              --entity-id entity_id \
              --entity-type company \
              --preference basic
components:
  schemas:
    WebhookMonitorItemRequest:
      type: object
      description: |
        Request to create a webhook monitor item.
      properties:
        entity_type:
          $ref: '#/components/schemas/WebhookMonitorEntityType'
          description: |
            Type of the entity to monitor.
        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'
      required:
        - entity_type
        - entity_id
        - preferences
    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.

````