How to Automate KYB Checks with a Secretary of State API

If your business onboards other businesses as customers, vendors, or partners, you already know the pain: manual KYB (Know Your Business) checks are slow, inconsistent, and expensive. A compliance analyst has to visit each state's Secretary of State website, enter the entity name, screenshot the results, and file it somewhere. Multiply that by hundreds of onboarding requests per month and you have a bottleneck that stalls revenue and creates compliance gaps.

There is a better way. A KYB automation API connected directly to Secretary of State records gives your compliance and engineering teams a programmatic, auditable, and scalable path to verify any US business entity in seconds. This guide explains exactly how to build that workflow, what the US regulatory landscape requires, and how to use the OpenSOSData API to get there.

Why KYB Automation Matters in 2024

Know Your Business verification is no longer optional window dressing. A convergence of federal regulations has made structured, documented business verification a legal baseline for financial institutions, fintech platforms, payment processors, and any entity subject to the Bank Secrecy Act (BSA).

The Regulatory Stack Driving KYB Requirements

Bank Secrecy Act (BSA) — 31 U.S.C. § 5311 et seq.
The BSA requires financial institutions to establish and maintain effective anti-money laundering (AML) programs. A core component of any AML program is customer due diligence (CDD), which explicitly includes verifying the identity of business entities that open accounts or establish relationships.

FinCEN Customer Due Diligence Rule — 31 CFR § 1010.230
FinCEN's CDD Rule, finalized in 2016 and enforced from 2018, requires covered financial institutions to identify and verify the identity of beneficial owners of legal entity customers. This means you must verify the business itself and the natural persons who own or control it. The rule applies to banks, credit unions, broker-dealers, mutual funds, and futures commission merchants.

Corporate Transparency Act (CTA) and FinCEN BOI Reporting — Effective January 1, 2024
The Corporate Transparency Act requires most US legal entities to file Beneficial Ownership Information (BOI) reports with FinCEN. While the BOI database is not yet publicly accessible, companies subject to the CTA must ensure their own registration data is accurate and current with state authorities. This makes Secretary of State data a critical first-line verification source — if an entity's state registration is inactive, dissolved, or fraudulent, that is an immediate red flag regardless of what a BOI report might say.

OFAC Sanctions Programs
The Office of Foreign Assets Control (OFAC) maintains sanctions lists that apply to businesses as well as individuals. Verifying that an entity is legitimately registered in a US state is a foundational step before any OFAC screening.

The bottom line: regulators expect documented, repeatable processes. A manual screenshot workflow does not meet that bar. A KYB automation API that pulls live Secretary of State data and stores structured, timestamped records does.

What Secretary of State Data Actually Tells You

Before building automation, it helps to understand what Secretary of State records contain and what compliance questions they answer.

Data Fields Available via the OpenSOSData API

These seven fields, returned in a single API call, answer the most fundamental KYB question: Does this business legally exist, and is it in good standing? Every other layer of due diligence — UBO verification, OFAC screening, credit checks — builds on this foundation.

Building a KYB Automation Workflow

A production-grade KYB automation pipeline typically has four stages:

1. Entity Data Collection — Capture business name, state of formation, and EIN during onboarding
2. Secretary of State Lookup — Query live state records via API
3. Risk Scoring — Apply business rules to the returned data (status checks, formation date thresholds, registered agent flags)
4. Decision and Audit Trail — Auto-approve, escalate for manual review, or reject; store structured results

The OpenSOSData API handles Stage 2 with a single REST call, covering all 50 US states plus DC, Puerto Rico, and USVI at $0.10 standard / $0.0314 Pi per lookup — no subscription required, with a minimum of just $3.14 (100 lookups). For most compliance teams, this means the API pays for itself on the first day it eliminates manual research time.

Practical Code Example: Python KYB Automation

Below is a working Python script that demonstrates a complete KYB check using the OpenSOSData API. You can extend this into a Django/Flask webhook, a Lambda function, or a Celery task depending on your stack.

import requests
import json
from datetime import datetime, timedelta

# --- Configuration ---
API_ENDPOINT = "https://api.opensosdata.com/v1/lookup"
API_KEY = "your_api_key_here"  # Get yours at https://app.opensosdata.com

# --- Risk thresholds (customize for your compliance policy) ---
MIN_BUSINESS_AGE_DAYS = 180  # Flag entities formed less than 6 months ago
ACCEPTABLE_STATUSES = {"active", "good standing", "in good standing"}


def run_kyb_check(entity_name: str, state: str) -> dict:
    """
    Run a KYB check for a given business entity against Secretary of State records.

    Args:
        entity_name: The legal name of the business to verify
        state: Two-letter US state code (e.g., 'DE', 'CA', 'NY')

    Returns:
        A structured dict containing verification result and risk flags
    """

    # Build the API request payload
    payload = {
        "business_name": entity_name,
        "state": state
    }

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    print(f"[KYB] Querying Secretary of State records for '{entity_name}' in {state}...")

    try:
        response = requests.post(
            API_ENDPOINT,
            headers=headers,
            json=payload,
            timeout=10  # Fail fast — don't block onboarding indefinitely
        )
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        # Network or API error — escalate for manual review rather than auto-reject
        return {
            "status": "error",
            "message": str(e),
            "decision": "manual_review",
            "risk_flags": ["api_unavailable"]
        }

    data = response.json()

    # If no entity was found, that itself is a major risk flag
    if not data.get("results"):
        return {
            "status": "not_found",
            "entity_name": entity_name,
            "state": state,
            "decision": "reject",
            "risk_flags": ["entity_not_found_in_sos_records"]
        }

    # Take the top result (best match)
    entity = data["results"][0]

    # --- Run risk checks ---
    risk_flags = []

    # Check 1: Entity status — is the business actually active?
    entity_status = entity.get("status", "").lower()
    if entity_status not in ACCEPTABLE_STATUSES:
        risk_flags.append(f"entity_status_is_{entity_status.replace(' ', '_')}")

    # Check 2: Business age — very new entities carry higher shell company risk
    formation_date_str = entity.get("formation_date")
    if formation_date_str:
        try:
            formation_date = datetime.strptime(formation_date_str, "%Y-%m-%d")
            age_days = (datetime.utcnow() - formation_date).days
            if age_days < MIN_BUSINESS_AGE_DAYS:
                risk_flags.append(f"entity_age_only_{age_days}_days")
        except ValueError:
            risk_flags.append("formation_date_parse_error")
    else:
        risk_flags.append("formation_date_missing")

    # Check 3: Registered agent address — flag if it looks like a mass-agent address
    registered_agent_address = entity.get("registered_agent_address", "")
    mass_agent_keywords = ["corporation service company", "ct corporation", "northwest registered"]
    if any(keyword in registered_agent_address.lower() for keyword in mass_agent_keywords):
        # Not an automatic reject, but worth noting for enhanced due diligence
        risk_flags.append("registered_agent_is_commercial_agent")

    # --- Build decision ---
    # Hard reject: entity not in good standing
    hard_reject_flags = [f for f in risk_flags if "status_is" in f]
    if hard_reject_flags:
        decision = "reject"
    # Manual review: any other risk flags present
    elif risk_flags:
        decision = "manual_review"
    # Clean pass
    else:
        decision = "approve"

    return {
        "status": "found",
        "decision": decision,
        "risk_flags": risk_flags,
        "entity": {
            "legal_name": entity.get("name"),
            "entity_type": entity.get("type"),
            "entity_id": entity.get("id"),
            "sos_status": entity.get("status"),
            "formation_date": entity.get("formation_date"),
            "registered_agent": entity.get("registered_agent"),
            "registered_agent_address": registered_agent_address,
            "state": state
        },
        "checked_at": datetime.utcnow().isoformat() + "Z"  # ISO 8601 timestamp for audit log
    }


# --- Example usage ---
if __name__ == "__main__":
    # Test with a sample business entity
    result = run_kyb_check(
        entity_name="Acme Technologies LLC",
        state="DE"
    )

    print("\n--- KYB RESULT ---")
    print(json.dumps(result, indent=2))

    # In production, you would save this result to your database
    # and trigger the appropriate onboarding workflow based on result["decision"]

Full API documentation, including all request/response schemas, is available at the OpenSOSData OpenAPI specification.

Integrating KYB Automation into Your Onboarding Stack

Trigger Points

The most effective KYB automation implementations trigger the Secretary of State lookup at multiple points, not just initial onboarding:

• Application submission: Run an immediate check before manual review begins. If the entity is dissolved or not found, reject automatically and notify the applicant.
• Periodic re-verification: Business statuses change. An entity that was active at onboarding can be administratively dissolved six months later. Schedule monthly or quarterly re-checks for active customers.
• Adverse event triggers: If a payment fails, a chargeback occurs, or fraud signals appear, a fresh SOS lookup should be part of the investigation workflow.

Storing Results for Regulatory Examination

FinCEN examiners and bank auditors want to see that your CDD records are contemporaneous and complete. Every API response should be stored as an immutable record with a timestamp, the raw response payload, and the decision your system made. The checked_at field in the code example above is a starting point — in production, store the full JSON response in a compliance data store separate from your transactional database.

KYB API Comparison: Manual vs. Automated

Getting Started with OpenSOSData

Creating an account and running your first lookup takes less than five minutes:

1. Sign up at app.opensosdata.com — no subscription required
2. Purchase a minimum of $3.14 in lookup credits (100 lookups at $0.0314 each)
3. Retrieve your API key from the dashboard
4. Make your first POST request to https://api.opensosdata.com/v1/lookup
5. Review the full schema in the OpenAPI specification

For compliance teams evaluating the API before purchasing, the pay-per-lookup pricing model means you can validate coverage for your specific use case without committing to a monthly contract.

Frequently Asked Questions