Guide · Node.js · TypeScript · SDK

Getting Started with the IsValid SDK

Go from zero to validated data in under five minutes. Install the official TypeScript SDK, create a client, run your first validation, and learn how to handle errors properly.

In this guide

  1. 1. Prerequisites
  2. 2. Installation
  3. 3. Create a client
  4. 4. Your first validation
  5. 5. More examples
  6. 6. Namespaced methods
  7. 7. Country-specific validators
  8. 8. Error handling
  9. 9. Next steps

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
ℹ️The free tier gives you 100 API calls per day — more than enough to follow this guide and start integrating.

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 });
✅Store your API key in an environment variable (e.g. ISVALID_API_KEY) and read it with process.env.ISVALID_API_KEY. Never commit API keys to version control.

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('DE811903812', { 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" }
ℹ️See the full API documentation for all 50+ validators and their response schemas.

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);
  }
}
Error classHTTP statusWhen
IsValidAuthError401Invalid or missing API key
IsValidRateLimitError429Daily call limit exceeded
IsValidError4xx / 5xxAny other API error
✅The SDK automatically retries on 429 and 5xx errors with exponential backoff (up to 3 retries by default). You only need to catch errors that persist after retries.

9. Next steps

📖

API Documentation

All 50+ endpoints with response schemas

💻

SDK on GitHub

Source code, issues, and contributions

📦

npm package

Version history and install stats

📚

All Guides

In-depth tutorials for specific validators

Start validating today

Free tier includes 100 API calls per day. No credit card required.

Get Free API KeyView Full API Docs