KnowFirm's onboarding API lets you automate Know Your Business (KYB) verification as part of your signup or merchant onboarding flow. This guide walks through the full lifecycle: submit, review, decide, and monitor.

The onboarding lifecycle

1. Submit — POST /v1/onboarding with a business name, EIN, LEI, or CIK. KnowFirm resolves the entity, runs a sanctions screen, and computes informational risk signals. The case is created as in_review with a recommendation.
2. Review — Read the case via GET /v1/onboarding/{id}. Inspect the resolved entity, sanctions matches, and risk signals. The recommendation is informational — your team or code makes the final decision.
3. Decide — POST /v1/onboarding/{id}/decision to approve or decline. Optionally attach a screening watch for continuous monitoring on approval.
4. Monitor — If you approved with create_watch: true, KnowFirm re-screens the entity nightly and sends alerts via webhook when the sanctions status changes.

Quick example (curl)

# 1. Submit a business for onboarding
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme corp"}' \
  https://api.knowfirm.com/v1/onboarding

# 2. Review the case (use the id from the response)
curl -H "X-API-Key: $KNOWFIRM_KEY" \
  https://api.knowfirm.com/v1/onboarding/CASE_ID

# 3. Approve and attach continuous monitoring
curl -X POST -H "X-API-Key: $KNOWFIRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","create_watch":true}' \
  https://api.knowfirm.com/v1/onboarding/CASE_ID/decision

TypeScript example

import { KnowFirm } from "./knowfirm";

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

async function onboardBusiness(name: string) {
  // Submit
  const filed = await kf.onboardingSubmit({ name });
  console.log("Case created:", filed.id, filed.recommendation);

  // Review: inspect risk signals
  const review = await kf.onboardingGet(filed.id);
  const sanctions = review.screening?.matches ?? [];

  if (sanctions.length > 0) {
    // Flag for manual review
    console.log("Sanctions matches found:", sanctions.length);
    return;
  }

  // Auto-approve with continuous monitoring
  await kf.onboardingDecide(filed.id, {
    decision: "approve",
    create_watch: true,
    reason: "No sanctions matches; automated approval",
  });
  console.log("Approved with monitoring");
}

await onboardBusiness("acme corp");

Python example

from knowfirm import KnowFirm
import os

kf = KnowFirm(api_key=os.environ["KNOWFIRM_KEY"])

def onboard_business(name: str):
    # Submit
    filed = kf.onboarding_submit(name=name)
    print(f"Case created: {filed['id']} — {filed['recommendation']}")

    # Review
    review = kf.onboarding_get(filed["id"])
    sanctions = review.get("screening", {}).get("matches", [])

    if sanctions:
        print(f"Sanctions matches found: {len(sanctions)}")
        return

    # Auto-approve with continuous monitoring
    kf.onboarding_decide(filed["id"], decision="approve", create_watch=True)
    print("Approved with monitoring")

onboard_business("acme corp")

Handling webhook alerts

When a watched entity's sanctions status changes, KnowFirm delivers a monitor.screening webhook. Set up a webhook endpoint in Dashboard → Monitors and verify signatures (see the webhook signature verification guide).

// Express webhook handler
app.post("/webhooks/knowfirm", (req, res) => {
  if (!verifyWebhook(req)) return res.sendStatus(400);

  const { type, data } = req.body;
  if (type === "monitor.screening") {
    // A watched entity matched a sanctions list
    console.log("Sanctions alert:", data.entity_name, data.matches);
    // Trigger your internal review process
  }
  res.sendStatus(200);
});

Costs

• Submission: 3 credits per POST /v1/onboarding (resolve + screen + risk signals)
• List / Get / Decide: not billed
• Continuous monitoring: 1 credit per month per active watch

FAQ

Is the onboarding recommendation a compliance determination? No. The recommendation is informational — it is not a compliance determination, credit decision, or consumer report. Your compliance team or automated rules make the final decision.

Can I auto-approve based on the recommendation? Yes, but the decision is yours. KnowFirm provides risk signals; you define the policy. The example above shows a simple auto-approve-if-no-sanctions pattern.

What happens if I decline a case? The case status changes to declined. No watch is created. You can still view the case and its audit trail.

Can I re-decide a case? No. A second decision on the same case returns 409 Conflict. Submit a new case if you need to re-evaluate.

What kinds of watches can I attach? The create_watch: true flag creates a screening watch. You can also create other watch types separately via POST /v1/watch — GLEIF lapse, complaint spike, new filing, or threshold watches.