Node.js SDK

Installation

npm install @bizverify/sdk

Requires Node.js 18+. Zero runtime dependencies.

Quick start

import { BizVerify } from '@bizverify/sdk';

const biz = new BizVerify({ apiKey: 'bv_live_...' });

// Verify a business
const result = await biz.verification.verify({
  entity_name: 'Acme Corporation',
  jurisdiction: 'us-fl',
});
console.log(result.status, result.data);

Passwordless auth

If you don’t have an API key yet:

const biz = new BizVerify();

// Step 1: Request a code
await biz.auth.requestAccess({
  email: 'you@company.com',
  accept_terms: true,
});

// Step 2: Verify code — client auto-configures
const { api_key } = await biz.auth.verifyAccess({
  email: 'you@company.com',
  code: '123456',
  label: 'my-app',
});

Verify and wait

For async verifications, verifyAndWait polls until complete:

const job = await biz.verification.verifyAndWait(
  { entity_name: 'Acme Inc', jurisdiction: 'us-fl' },
  {
    timeoutMs: 120_000,
    onStatusChange: (status) => console.log(status.status),
  },
);
console.log(job.data);

Search

// Single page
const page = await biz.search.find({
  entity_name: 'Acme',
  jurisdiction: 'us-fl',
  limit: 10,
});

// Auto-paginate
for await (const entity of biz.search.findAll({ entity_name: 'Acme' })) {
  console.log(entity.entity_name, entity.confidence);
}

Fetch a cached entity

Retrieve a previously verified business by its entity_id (returned from a verify or search call) — free, no credits charged.

const entity = await biz.entities.get('550e8400-e29b-41d4-a716-446655440000');

console.log(entity.entity_name, entity.status);
console.log(entity.registered_agent?.name);
console.log(entity.officers);
console.log(entity.last_verified_at);

Configuration

const biz = new BizVerify({
  apiKey: 'bv_live_...',
  baseUrl: 'https://api.bizverify.co',  // default
  maxRetries: 2,                          // retries on 5xx
  timeout: 30_000,                        // milliseconds
});

Credit tracking

const meta = biz.lastResponseMeta;
console.log(meta?.creditsRemaining, meta?.creditsCharged);

Error handling

import {
  BizVerify,
  AuthenticationError,
  InsufficientCreditsError,
  RateLimitError,
  NotFoundError,
  ValidationError,
} from '@bizverify/sdk';

try {
  await biz.verification.verify({ entity_name: 'Test', jurisdiction: 'us-fl' });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log('Need more credits');
  } else if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof NotFoundError) {
    console.log('Not found');
  } else if (err instanceof ValidationError) {
    console.log('Invalid request:', err.details);
  }
}

Full reference

See the SDK README on GitHub for the complete API.