KnowFirm

KnowFirm watches let you monitor a portfolio of businesses for sanctions list changes, GLEIF lapse, CFPB complaint spikes, and custom threshold crossings. Watches are evaluated nightly, and alerts are delivered via email and webhook.

Watch types

Kind What it monitors Alert trigger
screening U.S. Consolidated Screening List Entity appears on or is removed from a sanctions list
gleif_lapse GLEIF LEI status LEI status changes from "active" to lapsed/retired
complaint_spike CFPB complaints 7-day complaint count exceeds 2x the previous period (min 5)
new_filing New Form 5500 filings A new annual filing is detected for the watched entity
new_entity New source registrants A new entity appears in a source (e.g. new FDIC bank or NCUA credit union)
threshold Custom numeric field A field crosses a threshold you set (e.g. assets >= $1B)

Setting up watches

Screening watch (most common)

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme corp","kind":"screening"}' \
  https://api.knowfirm.com/v1/watch

GLEIF lapse watch

The entity must already have an LEI on record (404 otherwise):

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"apple inc","kind":"gleif_lapse"}' \
  https://api.knowfirm.com/v1/watch

Threshold watch

Fires when a numeric field crosses the threshold (on the crossing, not while it holds):

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"wells fargo","kind":"threshold","threshold":{"field":"participants","op":"gte","value":50000}}' \
  https://api.knowfirm.com/v1/watch

New entity watch (source-level)

Watches a whole source for new registrants, not a specific company:

curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_key":"fdic_institutions","kind":"new_entity"}' \
  https://api.knowfirm.com/v1/watch

Building a portfolio in code

import { KnowFirm } from "./knowfirm";

const kf = new KnowFirm({ apiKey: process.env.KNOWFIRM_KEY! });

const portfolio = [
  { name: "acme corp", kinds: ["screening"] },
  { name: "apple inc", kinds: ["screening", "gleif_lapse"] },
  { name: "wells fargo", kinds: ["screening", "complaint_spike"] },
];

for (const biz of portfolio) {
  for (const kind of biz.kinds) {
    await kf.watchCreate({ name: biz.name, kind });
    console.log(`Watch created: ${biz.name} (${kind})`);
  }
}

Handling alerts via webhook

Configure a webhook in Dashboard → Monitors. Alerts arrive as monitor.* events:

See the webhook signature verification guide for how to verify webhook signatures.

Managing watches

# List all watches
curl -H "X-API-Key: $KNOWFIRM_KEY" https://api.knowfirm.com/v1/watch

# Delete a watch by id
curl -X DELETE -H "X-API-Key: $KNOWFIRM_KEY" \
  "https://api.knowfirm.com/v1/watch?id=WATCH_ID"

Costs

Each active watch costs 1 credit per month, billed on evaluation. Creating and deleting watches is free. Alerts delivered via webhook are not separately billed.

FAQ

How often are watches evaluated? Watches are evaluated nightly. The exact time depends on the data refresh schedule for each source.

Can I watch a business by EIN or CIK instead of name? Yes. Pass a subject_key from a prior resolve instead of name for exact matching.

What happens if a watched entity is delisted from sanctions? You receive a monitor.screening alert indicating the entity is no longer on the list.

Is the complaint_spike alert a consumer report? No. CFPB complaint counts are informational, company-level data from the public Consumer Complaint Database. They are not a consumer report, not a creditworthiness score, and not for FCRA-covered eligibility decisions.

Can I set up alerts without a webhook? Yes. Alerts are also sent to the account email. Webhooks are optional but recommended for automated workflows.