US Entity Lookup in Node.js: Quick Start Guide

If you're building a compliance workflow, a fintech product, or any platform that onboards US businesses, you already know the pain: manually checking Secretary of State portals across 50 states is slow, inconsistent, and impossible to scale. Entity lookup in Node.js via a structured REST API changes that equation entirely. In minutes, you can verify a business entity's legal standing, formation date, registered agent, and status — all programmatically, without leaving your codebase.

This guide walks US developers and compliance engineers through integrating the OpenSOSData API into a Node.js application, with working code, regulatory context, and practical tips for building production-ready KYB pipelines.

Why Business Entity Verification Matters for US Professionals

The regulatory stakes for onboarding unverified businesses in the United States have never been higher. Three major frameworks drive demand for reliable entity lookup:

FinCEN Beneficial Ownership Information (BOI) Requirements

Under the Corporate Transparency Act, FinCEN's Beneficial Ownership Information reporting rule — effective January 1, 2024 — requires most US entities to disclose their beneficial owners. For platforms that onboard business customers, confirming a company's registered status is the first step before you can reasonably collect and verify BOI. An entity that doesn't legally exist cannot have valid beneficial owners.

Bank Secrecy Act (BSA) and KYB Obligations

The BSA requires financial institutions and many money services businesses to maintain robust Know Your Business (KYB) programs. Regulators expect you to verify that a business is duly formed, currently active, and operating under its legal name. Relying on self-reported business information without cross-referencing an authoritative state source creates documented BSA compliance gaps — the kind that show up in enforcement actions.

OFAC and Sanctions Screening Context

OFAC sanctions screening works best when you start with verified legal entity names and IDs. If a customer provides a slightly different business name than what appears in state records, your screening logic can miss matches. Pulling the canonical entity name from a Secretary of State database first makes downstream screening more accurate.

What the OpenSOSData API Returns

The OpenSOSData API covers all 50 US states, Washington D.C., Puerto Rico, and the U.S. Virgin Islands — more than 23 million business entities. For each lookup, it returns:

• Entity name — the legal registered name on file
• Entity type — LLC, corporation, LP, etc.
• Entity ID — the state-assigned registration number
• Status — active, dissolved, revoked, etc.
• Formation date — when the entity was registered
• Registered agent name and address

Lookups use a simple POST endpoint: https://api.opensosdata.com/v1/lookup. Full schema documentation is available at opensosdata.com/openapi.yaml.

Pricing at a Glance

Billing is pay-as-you-go with no monthly minimums. Live lookups hit the state source in real time; cached lookups return recently retrieved data at a fraction of the cost — useful for batch verification or repeat checks on the same entity.

Setting Up Your Node.js Environment

Before writing any code, make sure you have Node.js 18 or later installed. The built-in fetch API is available natively, so you don't need node-fetch or axios for basic calls. That said, this guide includes an axios example as well, since many enterprise Node.js codebases already use it.

First, grab your API key by signing up at app.opensosdata.com. Store it as an environment variable — never hardcode credentials in source files.

# In your shell or .env file
OPENSOSDATA_API_KEY=your_api_key_here

Quick Start: Entity Lookup with Native fetch (Node.js 18+)

// entityLookup.js
// Performs a live US business entity lookup using the OpenSOSData API
// Requires Node.js 18+ for native fetch support

const API_URL = 'https://api.opensosdata.com/v1/lookup';
const API_KEY = process.env.OPENSOSDATA_API_KEY; // Load from environment

async function lookupEntity({ businessName, state, live = true }) {
  // Build the request payload
  const payload = {
    business_name: businessName,
    state: state,          // Two-letter state code, e.g. "DE", "CA", "TX"
    live: live             // true = real-time state source; false = cached result
  };

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify(payload)
  });

  // Surface API errors clearly for debugging
  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`API error ${response.status}: ${errorBody}`);
  }

  const data = await response.json();
  return data;
}

// Example: verify "Acme Technologies LLC" in Delaware
(async () => {
  try {
    const result = await lookupEntity({
      businessName: 'Acme Technologies LLC',
      state: 'DE',
      live: true   // $0.10 live lookup — hits Delaware's state source
    });

    console.log('Entity Name:', result.entity_name);
    console.log('Entity Type:', result.entity_type);
    console.log('Entity ID:  ', result.entity_id);
    console.log('Status:     ', result.status);       // e.g. "Active"
    console.log('Formed:     ', result.formation_date);
    console.log('Reg. Agent: ', result.registered_agent?.name);
    console.log('Agent Addr: ', result.registered_agent?.address);

    // Basic compliance gate: reject entities that are not active
    if (result.status !== 'Active') {
      console.warn('WARNING: Entity is not in active standing. Review before onboarding.');
    } else {
      console.log('Entity verified as active. Proceed with KYB workflow.');
    }
  } catch (err) {
    console.error('Lookup failed:', err.message);
    process.exit(1);
  }
})();

Run it from your terminal:

OPENSOSDATA_API_KEY=your_key_here node entityLookup.js

Alternative: Using Axios for Enterprise Codebases

// entityLookupAxios.js
// Same lookup using axios — common in Express.js and NestJS projects

const axios = require('axios');

const API_URL = 'https://api.opensosdata.com/v1/lookup';
const API_KEY = process.env.OPENSOSDATA_API_KEY;

async function lookupEntityAxios(businessName, state) {
  try {
    const response = await axios.post(
      API_URL,
      {
        business_name: businessName,
        state: state,
        live: true  // Real-time verification for KYB compliance
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        timeout: 15000  // 15-second timeout; live lookups depend on state systems
      }
    );

    return response.data;
  } catch (error) {
    // Axios wraps HTTP errors; extract meaningful message
    const msg = error.response
      ? `Status ${error.response.status}: ${JSON.stringify(error.response.data)}`
      : error.message;
    throw new Error(`Entity lookup failed: ${msg}`);
  }
}

module.exports = { lookupEntityAxios };

Integrating Entity Lookup into a KYB Onboarding Flow

A real KYB pipeline doesn't stop at a single lookup. Here's how entity lookup fits into a broader compliance sequence in a Node.js backend:

1. Collect business inputs — legal name, state of formation, EIN (for later tax verification).
2. Run a live entity lookup — confirm the entity exists and is active in the stated jurisdiction.
3. Normalize the legal name — use the returned entity_name for all downstream processing, including OFAC screening, to avoid name mismatch issues.
4. Collect beneficial ownership data — now that the entity is verified, gather BOI per FinCEN requirements.
5. Store the entity ID — save the state-issued entity_id in your database as the authoritative reference for future re-verification checks.
6. Schedule periodic re-verification — use cached lookups ($0.01) to periodically confirm the entity remains in good standing without inflating costs.

Handling Edge Cases in Production

Entities Registered in Multiple States

A Delaware-incorporated company may operate as a foreign entity in California and Texas. The API accepts a state parameter per call, so run separate lookups for each jurisdiction where the entity has registered. Compare statuses across states to build a complete picture.

Rate Limiting and Retry Logic

For batch onboarding jobs, implement exponential backoff. State-side data sources can occasionally be slow, which may cause timeouts. A simple retry wrapper with a 2-4 second delay between attempts keeps your pipeline resilient.

Caching Strategy

For entities you've recently verified, use the cached lookup option to save cost. Reserve live lookups for initial onboarding and scheduled compliance re-checks (e.g., quarterly). This alone can reduce your per-entity verification cost from $0.10 to $0.01 on routine checks.

Frequently Asked Questions

Next Steps

Entity lookup in Node.js is a straightforward integration with significant compliance value. A few dozen lines of code give your platform verifiable, authoritative data on any US business entity — the foundation of a defensible KYB program.

To get started: sign up for an API key at app.opensosdata.com, review the full schema at opensosdata.com/openapi.yaml, and explore coverage details and pricing at opensosdata.com. Your first lookup can be live in under fifteen minutes.