Getting Started with the IsValid SDK

1. Prerequisites

Before you start, make sure you have:

• Node.js 18+ (the SDK uses the native fetch API)
• A free IsValid account — sign up here
• An API key from your dashboard

2. Installation

Install the SDK from npm:

npm install @isvalid-dev/sdk

Or use your preferred package manager:

yarn add @isvalid-dev/sdk
# or
pnpm add @isvalid-dev/sdk
# or
bun add @isvalid-dev/sdk

The package ships ESM and CJS builds, has zero dependencies, and weighs ~1.5 KB minified + brotli.

3. Create a client

Import createClient and pass your API key:

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: 'your-api-key' });

That's it — you're ready to validate. The client uses sensible defaults: 10-second timeout, automatic retry with exponential backoff on 429 and 5xx errors.

You can customize these defaults if needed:

const iv = createClient({
  apiKey: 'your-api-key',
  timeout: 15000,         // 15 seconds (default: 10000)
  retry: {
    maxRetries: 5,        // default: 3
    initialDelayMs: 1000, // default: 500
    maxDelayMs: 30000,    // default: 10000
  },
});

// Or disable retry entirely
const iv = createClient({ apiKey: 'your-api-key', retry: false });

4. Your first validation

Let's validate an email address with an MX record check:

const result = await iv.email('user@example.com', { checkMx: true });
console.log(result);

Response:

{
  "valid": true,
  "local": "user",
  "domain": "example.com",
  "mxValid": true
}

Every response includes a valid boolean. When valid is true, TypeScript automatically narrows the type so you get full IntelliSense on all returned fields:

const result = await iv.email('user@example.com', { checkMx: true });

if (result.valid) {
  // TypeScript knows these fields exist
  console.log(result.domain);  // "example.com"
  console.log(result.mxValid); // true
} else {
  // result is { valid: false }
  console.log('Invalid email');
}

5. More examples

The SDK exposes 50+ validators as simple method calls. Here are a few common ones:

IBAN

const iban = await iv.iban('DE89370400440532013000');
// => { valid: true, countryCode: "DE", bankName: "Commerzbank", bankBic: "COBADEFFXXX", ... }

VAT number with VIES check

const vat = await iv.vat('DE123456788', { checkVies: true });
// => { valid: true, countryCode: "DE", isEU: true, vies: { checked: true, valid: true, name: "..." } }

Phone number

const phone = await iv.phone('+48501234567');
// => { valid: true, countryCode: "PL", callingCode: "48", type: "MOBILE", e164: "+48501234567", ... }

Credit card (POST endpoint)

const card = await iv.creditCard('4111111111111111');
// => { valid: true, network: "Visa" }

6. Namespaced methods

Some endpoints group related functionality under namespaces. These support both validation and data listing:

// LEI — validate, search by name, list LOUs
const lei = await iv.lei('7LTWFZYICNSX8D621K86');
const search = await iv.lei.search('Apple', { country: 'US', limit: 5 });
const lous = await iv.lei.lous();

// Country / Currency / Language — validate or list all
const country = await iv.country('PL');
const countries = await iv.country.list();

const currency = await iv.currency('USD');
const currencies = await iv.currency.list();

const language = await iv.language('en');
const languages = await iv.language.list();

// IATA — airports, airlines, flights
const airport = await iv.iata.airport('WAW');
const airline = await iv.iata.airline('LH');
const airlines = await iv.iata.airline.list();
const flight = await iv.iata.flight('LH1234');

7. Country-specific validators

Validators specific to a country are grouped under two-letter country code namespaces:

// Poland
await iv.pl.pesel('44051401358');
await iv.pl.regon('012345678', { lookup: true });
await iv.pl.krs('0000123456', { lookup: true });

// Brazil
await iv.br.cnpj('11.222.333/0001-81');
await iv.br.cpf('123.456.789-09');

// Australia
await iv.au.abn('51824753556');

// Spain
await iv.es.nif('12345678Z');

// India
await iv.in.gstin('27AAPFU0939F1ZV');

// United States
await iv.us.npi('1234567893');

// United Kingdom
await iv.gb.sortCode('12-34-56');

8. Error handling

The SDK provides three error classes so you can handle each failure mode separately:

import {
  IsValidError,
  IsValidAuthError,
  IsValidRateLimitError,
} from '@isvalid-dev/sdk';

try {
  const result = await iv.email('test@example.com');
} catch (err) {
  if (err instanceof IsValidRateLimitError) {
    // 429 — you've exceeded your daily limit
    console.log('Rate limited, retry after:', err.retryAfter, 'seconds');
  } else if (err instanceof IsValidAuthError) {
    // 401 — invalid or missing API key
    console.log('Invalid API key');
  } else if (err instanceof IsValidError) {
    // Other API error (4xx / 5xx)
    console.log('API error:', err.status, err.body.error);
  }
}

9. Next steps

Node.js integration notes

Building a IsValid SDK for Node.js pipeline in Node.js calls for a layered validation strategy: fast client-side schema checks for obvious format errors, then IsValid API calls for semantic correctness. TypeScript's type system enforces this layering at compile time — branded types for each validated identifier ensure that downstream functions only accept verified values. The IsValid SDK ships with full TypeScript declarations covering all response fields for every identifier type in the pipeline.

The Node.js ecosystem pairs well with IsValid SDK for Node.js workflows. Usezod orjoi for structural schema validation, then IsValid for domain-specific semantic checks. For orchestrating multiple concurrent validation calls — typical in multi-identifier scenarios — Promise.allSettled()collects all results without aborting on the first failure, which is essential for returning a complete validation report to the client in a single response.

For production deployments, instrument the IsValid SDK for Node.js validation layer with structured logging using pino. Log each validation call at debug level with the identifier type, result, and response time. Expose Prometheus counters for validation failures by type — spikes often indicate upstream data quality changes before they cause downstream business errors.

• Validate process.env.ISVALID_API_KEY at server startup to catch misconfigured deployments early
• Use jest.mock() to stub the SDK in unit tests; keep a separate integration test suite for end-to-end flows
• Normalise all incoming identifier strings before validation: trim whitespace, remove formatting separators, standardise case
• Return the full IsValid API response to your clients where appropriate — parsed fields such as country, type, and issuer often save a second lookup

When making HTTP calls to the IsValid API directly (without the SDK), the choice between fetch and axios is largely a matter of preference. The native fetch API is available in Node.js 18+ without any additional dependency and is sufficient for simple request/response flows. axios adds automatic JSON parsing, request/response interceptors, and a cleaner timeout API (axios.create({ timeout: 5000 })), which makes it easier to centralise the Authorization header and retry logic in one place. For high-throughput services that make many concurrent API calls, consider undici — the HTTP client underlying Node.js fetch — used directly for its connection pooling and lower overhead.