For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact SalesGet Support
HomeGuidesAPI reference
HomeGuidesAPI reference
  • Get started
    • Quickstart—Verify a Business
    • Quickstart—Register an entity for payroll taxes
    • Learn how Middesk works
    • Security
    • Changelog
  • Build with Middesk
    • Get your API keys
    • Understand API changes
    • Status codes and errors reference
    • Implement webhooks
    • Secure webhooks
    • Use GraphQL
    • Connect MCP
  • Verify a business (KYB)
    • Verify TIN
    • Verify name and address
    • Verify Secretary of State status
    • Verify owners and officers
    • Screen for sanctions and watchlists
    • Search for adverse media
    • Search for Politically Exposed Persons
    • Implement KYC
    • Discover connections
    • Evaluate online presence
    • Assess credit risk
    • Accelerate onboarding
    • Monitor business activity
      • How Monitoring works
      • Monitor watchlist hits
      • Monitor bankruptcies
      • Monitor liens
    • Manage business entities
    • Work with agents
LogoLogo
Contact SalesGet Support
On this page
  • Prerequisites
  • Learn the monitoring lifecycle
  • Monitor businesses
Monitor business activity

How monitoring works

Was this page helpful?
Previous

Monitor business names

Next
Built with

This guide describes how to use monitoring to listen for changes associated with subscribed businesses on Middesk’s Identity Platform.

Prerequisites

Before you begin:

  • Ensure that you can authenticate against the Middesk API, create businesses, and ingest Middesk results with webhooks

Learn the monitoring lifecycle

Monitoring flow · 2 phases
How monitoring works for a business
How Monitoring Works

A business moves through two phases: Verification (Middesk processes the business and delivers insights), then Monitoring (the business is subscribed via dashboard, auto-enable, or policy, changes are detected, and webhook notifications are sent).

01 · VerificationMiddeskProcesses Business andDelivers Insightsneeds_review02 · MonitoringManualDashboard or APIenable MonitoringFor individual businessesAutomaticAuto-enableMonitoringFor all businessesPolicyPolicy enableMonitoringFor matching businessesMiddesk · StateMonitoring EnabledBusiness subscribed to change detectionMonitoring can be enabled for the following event types:bankruptcy.createdbankruptcy.updatedregistration.createdregistration.updatedwatchlist_result.createdwatchlist_result.updatedtin.createdtin.updatedMiddeskChange DetectedNotificationWebhook event andemail notification sent

Here’s the typical lifecycle of a business with monitoring enabled:

  1. A business gets created with the POST /businesses endpoint.
  1. The business is subscribed to monitoring.
  2. At some point in the future, a change to that business is detected. The business record updates.
  3. Middesk sends a webhook event to registered webhook endpoint(s).
  4. The client application ingests and evaluates the change in the business record.

Monitor businesses

1

Subscribe a business

You can enable monitoring on Middesk businesses using four different strategies.

With the API
With the Dashboard

Use the POST /monitor API to create, update, and delete business monitors for fine-grained control within your application.

2

Set up and listen for monitoring webhook events

Depending on the type of monitor that you want to listen for, register a new webhook with the corresponding event types selected.

3

Consume and evaluate monitoring events

Webhook requests contain a few top level fields:

  • data. Contains the event-specific payload and all the information about a monitoring event.

    Event payloads represent the change identified in the business record rather than full business object. For more granular control, use event payloads.

  • id. The Middesk-generated identifier for the webhook. It’s useful for debugging. Use it to search for pertinent webhook logs on the Middesk webhooks page.

  • type. The type of webhook provided.

  • account_id. The Middesk-generated identifier for the account the webhook is sent for. Useful if you route traffic across multiple Middesk accounts.

When a monitoring event is triggered, the composite business record and business insights update.

While it’s possible to consume monitoring-specific payloads (example payloads), for typical use cases, it’s usually sufficient to retrieve the business associated with the event.

To retrieve the business associated with the event:

  1. Access the business’s ID using the data.object.business_id field included in the webhook payload.

  2. Retrieve the Middesk business using the GET /businesses endpoint.

    The response includes the full business record.

Get a demo
Contact your account manager or contact sales to inquire about access.