Monitor a company list for M&A deals using structured outputs

Overview

When tracking M&A activity across a large list of companies, such as a Fortune 25-style watchlist, the naive approach is to poll a search per company, or stand up a separate feed per company. Neither scales: polling means paying for requests whether or not anything changed, and one feed per company means managing dozens of schedules and webhook endpoints for what is really a single workflow. A Seltz monitor batches many searches under one schedule and tells you about new results with a webhook, so you get one feed and one notification channel for the whole list instead of one per company. This tutorial walks through that pattern: one monitor with a search request per company, a webhook to avoid polling, and Answer with a response_format schema to verify and extract deal details from each new result rather than parsing the raw record yourself.

Outline

Create one monitor with a search request per company, and attach a webhook.
Verify and handle a webhook delivery.
Turn each new result into structured deal information with a single Answer call.
Alert someone when a deal is detected.

The examples in this tutorial track a handful of large companies standing in for a full watchlist, but the same pattern applies to any list of entities and any kind of event you can phrase as a search.

1. Create one monitor with a search request per company, and attach a webhook.

A monitor’s search_requests is a list. One call to create can hold a search per company, up to 1,000 requests per monitor. Attach a webhook in the same call, so you’re notified when a run finishes rather than polling for new records.

A monitor’s name is unique per organization among live monitors: creating a second monitor with the same name returns 409 ALREADY_EXISTS. The webhook secret is returned once, in the create response, and never again, so store it immediately.

from seltz import Seltz

client = Seltz(api_key="your-api-key")

# A representative sample of a Fortune 25-style watchlist. Extend with your
# full list, up to the 1,000-request limit per monitor.
WATCHLIST = [
    "Walmart",
    "Amazon",
    "Apple",
    "Berkshire Hathaway",
    "UnitedHealth Group",
]

response = client.monitor.create(
    "watchlist-ma-deals",
    cadence="6h",
    search_requests=[f"{company} acquisition merger" for company in WATCHLIST],
    webhook={
        "url": "https://example.com/seltz/monitors",
        "events": ["run.completed"],
    },
)

monitor = response.monitor
print(monitor.monitor_id)

# Returned once, at create, and never again.
webhook_secret = response.webhook_secret

import { Seltz } from "seltz";

const client = new Seltz({ apiKey: "your-api-key" });

// A representative sample of a Fortune 25-style watchlist. Extend with your
// full list, up to the 1,000-request limit per monitor.
const watchlist = [
  "Walmart",
  "Amazon",
  "Apple",
  "Berkshire Hathaway",
  "UnitedHealth Group",
];

const response = await client.monitor.create({
  name: "watchlist-ma-deals",
  cadence: "6h",
  searchRequests: watchlist.map((company) => `${company} acquisition merger`),
  webhook: {
    url: "https://example.com/seltz/monitors",
    events: ["run.completed"],
  },
});

const monitor = response.monitor;
console.log(monitor!.monitorId);

// Returned once, at create, and never again.
const webhookSecret = response.webhookSecret;

curl -X POST https://api.seltz.ai/v1/monitors \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "watchlist-ma-deals",
    "cadence": "6h",
    "search_requests": [
      {"query": "Walmart acquisition merger"},
      {"query": "Amazon acquisition merger"}
    ],
    "webhook": {
      "url": "https://example.com/seltz/monitors",
      "events": ["run.completed"]
    }
  }'

cadence is a judgment call: deal news is not minute-sensitive, so a longer cadence like 6h keeps cost down without meaningfully delaying an alert. See Concepts for the full grammar and the one-hour floor.

2. Verify and handle a webhook delivery.

Deliveries are signed following the Standard Webhooks specification. Verify with the Standard Webhooks library for your language rather than write custom signature-checking code. This is the same verification shown in Webhooks.

from standardwebhooks import Webhook, WebhookVerificationError


def handle_delivery(monitor_id: str, secret: str, headers: dict[str, str], body: bytes):
    try:
        payload = Webhook(secret).verify(body, headers)
    except WebhookVerificationError:
        return

    if payload["event"] != "run.completed":
        return

    run_id = payload["run"]["run_id"]
    page = client.monitor.list_run_records(monitor_id, run_id, limit=100)
    for record in page.records:
        # Step 3 turns each new record into structured deal information.
        process_record(record.search_result.document)

import { Webhook, WebhookVerificationError } from "standardwebhooks";

async function handleDelivery(
  monitorId: string,
  secret: string,
  headers: Record<string, string>,
  body: Buffer,
) {
  let payload: any;
  try {
    payload = new Webhook(secret).verify(body.toString("utf8"), headers);
  } catch (e) {
    if (e instanceof WebhookVerificationError) return;
    throw e;
  }

  if (payload.event !== "run.completed") return;

  const runId = payload.run.run_id;
  const page = await client.monitor.listRunRecords(monitorId, runId, { limit: 100 });
  for (const record of page.records) {
    if (record.payload.case !== "searchResult") continue;
    const document = record.payload.value.document;
    if (!document) continue;
    // Step 3 turns each new record into structured deal information.
    await processRecord(document);
  }
}

Both samples take the raw request body, which is the bytes as received before any JSON parsing. A framework that returns an already-parsed object has discarded the raw bytes, so use the raw-body accessor your framework provides. This is the body of whatever route handler receives the webhook POST in your framework of choice, not a complete server.

3. Turn each new result into structured deal information with a single Answer call.

Rather than parsing the record’s Markdown content yourself to decide whether it’s a real deal, use answer with a response_format JSON schema. The only thing pulled from the record itself is its headline, used to anchor a fresh, targeted question. The verification and extraction are entirely Answer’s job.

import json

DEAL_FORMAT = {
    "type": "json_schema",
    "json_schema": {
        "name": "deal_info",
        "schema": {
            "type": "object",
            "properties": {
                "is_deal": {"type": "boolean"},
                "acquirer": {"type": ["string", "null"]},
                "target": {"type": ["string", "null"]},
                "status": {"type": ["string", "null"]},
            },
            "required": ["is_deal", "acquirer", "target", "status"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

def process_record(document) -> None:
    headline = document.content.splitlines()[0].lstrip("# ").strip()

    response = client.answer(
        f"{headline}. Is this a confirmed M&A deal? If so, name the acquirer, "
        "the target, and the deal status (announced, completed, or terminated).",
        response_format=DEAL_FORMAT,
    )
    try:
        deal = json.loads(response.answer)
    except json.JSONDecodeError:
        return

    if deal["is_deal"]:
        alert_deal(deal, document.url)  # Step 4

const dealFormat = {
  type: "json_schema",
  json_schema: {
    name: "deal_info",
    schema: {
      type: "object",
      properties: {
        is_deal: { type: "boolean" },
        acquirer: { type: ["string", "null"] },
        target: { type: ["string", "null"] },
        status: { type: ["string", "null"] },
      },
      required: ["is_deal", "acquirer", "target", "status"],
      additionalProperties: false,
    },
    strict: true,
  },
};

async function processRecord(document: { content: string; url: string }) {
  const headline = document.content.split("\n")[0].replace(/^#+\s*/, "").trim();

  const result = await client.answer({
    query:
      `${headline}. Is this a confirmed M&A deal? If so, name the acquirer, ` +
      "the target, and the deal status (announced, completed, or terminated).",
    responseFormat: dealFormat,
  });

  let deal;
  try {
    deal = JSON.parse(result.answer);
  } catch {
    return;
  }

  if (deal.is_deal) {
    await alertDeal(deal, document.url); // Step 4
  }
}

curl -X POST https://api.seltz.ai/v1/answer \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Apple to acquire Northwind Robotics for $2B. Is this a confirmed M&A deal? If so, name the acquirer, the target, and the deal status (announced, completed, or terminated).",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "deal_info",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "is_deal": {"type": "boolean"},
            "acquirer": {"type": ["string", "null"]},
            "target": {"type": ["string", "null"]},
            "status": {"type": ["string", "null"]}
          },
          "required": ["is_deal", "acquirer", "target", "status"],
          "additionalProperties": false
        }
      }
    }
  }'

Not every new result is a real deal: an article that merely mentions a watchlist company is expected, so expect the value of is_deal to often be false. Both outcomes below are responses from the same schema, used to structure responses from the the watchlist in step 1. The first result is a confirmed deal, and the second is a routine article that just happened to match the search.

{
  "is_deal": true,
  "acquirer": "Walmart",
  "target": "Vizio",
  "status": "announced"
}

{
  "is_deal": false,
  "acquirer": null,
  "target": null,
  "status": null
}

Truncated generation can leave response.answer unparsable as JSON. The try/except block above skips the record. A malformed response_format schema is different: it’s rejected before the request is billed, but that’s a one-time schema-authoring mistake that raises on every call, not a per-record condition. Write and test DEAL_FORMAT once rather than expecting the loop above to handle it.

4. Alert someone when a deal is detected.

alert_deal stands in for however you notify a person: for example, Slack, email, PagerDuty, or your own on-call tooling. Swap in your own integration; the important part is passing along the structured fields Answer already extracted, not the raw record.

def alert_deal(deal: dict, source_url: str) -> None:
    message = (
        f"Possible deal detected: {deal['acquirer']} / {deal['target']} "
        f"({deal['status']})\nSource: {source_url}"
    )
    # Replace with your own notification channel.
    print(message)

async function alertDeal(deal: { acquirer: string; target: string; status: string }, sourceUrl: string) {
  const message =
    `Possible deal detected: ${deal.acquirer} / ${deal.target} ` +
    `(${deal.status})\nSource: ${sourceUrl}`;
  // Replace with your own notification channel.
  console.log(message);
}

Next steps

Monitor Concepts — Monitors, runs, records and webhooks
Webhooks — Attaching, disabling and removing a webhook
Monitor Reference — Endpoints, limits and errors
Answer API Reference — Full response_format specification

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Monitor a company list for M&A deals using structured outputs

Overview

Outline

1. Create one monitor with a search request per company, and attach a webhook.

2. Verify and handle a webhook delivery.

3. Turn each new result into structured deal information with a single Answer call.

4. Alert someone when a deal is detected.

Next steps

​Overview

​Outline

​1. Create one monitor with a search request per company, and attach a webhook.

​2. Verify and handle a webhook delivery.

​3. Turn each new result into structured deal information with a single Answer call.

​4. Alert someone when a deal is detected.

​Next steps

Overview

Outline

1. Create one monitor with a search request per company, and attach a webhook.

2. Verify and handle a webhook delivery.

3. Turn each new result into structured deal information with a single Answer call.

4. Alert someone when a deal is detected.

Next steps