Skip to main content
The official Node.js SDK for the Data Legion API. Written in TypeScript with zero external dependencies.

​
Installation

npm install datalegion
Requires Node.js 20+.

​
Authentication

Get an API key by signing up for free; it’s available in your dashboard after approval. The same key works across the API, SDKs, MCP server, and CLI. 
// Set DATALEGION_API_KEY in your environment
import DataLegion from 'datalegion';
const client = new DataLegion();

​
Person

​
Enrichment

Look up a person by email, phone, name, LinkedIn, or other identifiers. 
import DataLegion from 'datalegion';

const client = new DataLegion({ apiKey: 'legion_...' });

const person = await client.person.enrich({
  email: 'jane.doe@example.com',
});

console.log(person.full_name);          // "Jane Doe"
console.log(person.job_title);          // "VP of Engineering"
console.log(person.company_name);       // "Acme Corp"
console.log(person.city, person.state); // "San Francisco" "California"
Return multiple matches with confidence scores by setting multiple_results: true. 
const matches = await client.person.enrich({
  first_name: 'Jane',
  last_name: 'Doe',
  company: 'Acme',
  multiple_results: true,
  limit: 5,
  min_confidence: 'high',
});

console.log(`Found ${matches.total} matches`);
for (const match of matches.matches) {
  console.log(
    `${match.person.full_name} - ${match.match_metadata?.match_confidence}`
  );
}
Query people using a SQL SELECT against the people table. The query must start with SELECT and must not include a LIMIT clause — pass limit as a parameter. 
const results = await client.person.search({
  query:
    "SELECT * FROM people WHERE job_title ILIKE '%engineer%' AND city = 'San Francisco'",
  limit: 25,
});

// `total` reflects the full row count matching the WHERE clause across the
// database — useful for TAM / market-sizing — while `matches` is capped at `limit`.
console.log(`${results.matches.length} of ${results.total} total matches`);
for (const match of results.matches) {
  console.log(`${match.person.full_name} - ${match.person.job_title}`);
}

​
Discovery

Find people using natural language. 
const results = await client.person.discover({
  query: 'product managers at AI startups in New York',
  limit: 10,
});

// The generated SQL is included in the response
console.log(`Generated query: ${results.generatedQuery}`);

for (const match of results.matches) {
  console.log(`${match.person.full_name} at ${match.person.company_name}`);
}

​
Company

​
Enrichment

Look up a company by domain, name, ticker, or LinkedIn. 
const company = await client.company.enrich({
  domain: 'google.com',
});

console.log(company.name);                         // CleanedRaw object
console.log(company.industry);                     // "Internet"
console.log(company.legion_employee_count);        // 182000
console.log(company.legion_employee_growth_rate);  // { "1m": 0.02, "3m": 0.05, ... }

​
Search

Query companies using SQL WHERE syntax. 
const results = await client.company.search({
  query: "industry = 'Artificial Intelligence' AND legion_employee_count > 50",
  limit: 20,
});

for (const match of results.matches) {
  console.log(`${match.company.name} - ${match.company.industry}`);
}

​
Discovery

Find companies using natural language. 
const results = await client.company.discover({
  query: 'fintech companies in London with over 200 employees',
  limit: 10,
});

for (const match of results.matches) {
  console.log(`${match.company.name} - ${match.company.legion_employee_count} employees`);
}

​
Utility Endpoints

Utility endpoints are free and don’t consume credits.

​
Clean Fields

const cleaned = await client.utility.clean({
  fields: {
    email: '  JANE.DOE+work@GMAIL.COM  ',
    phone: '(555) 123-4567',
    domain: 'https://www.Google.com/about',
  },
});

for (const [field, result] of Object.entries(cleaned.results)) {
  console.log(`${field}: ${result.original} -> ${result.cleaned}`);
}

​
Hash Email

const hashed = await client.utility.hashEmail({
  email: 'jane@example.com',
});

console.log(hashed.normalized_email);  // "jane@example.com"
console.log(hashed.hashes.sha256);     // SHA-256 hash
console.log(hashed.hashes.md5);        // MD5 hash

​
Validate Data

const result = await client.utility.validate({
  email: 'not-an-email',
  phone: '+15551234567',
  company: 'Google',
});

if (!result.valid) {
  for (const err of result.errors) {
    console.log(`${err.field}: ${err.error}`);
  }
}

​
Response Metadata

After each request, response metadata is available on the client. 
await client.person.enrich({ email: 'jane@example.com' });

console.log(client.requestId);           // Unique request ID
console.log(client.creditsUsed);         // Credits consumed
console.log(client.creditsRemaining);    // Remaining balance
console.log(client.rateLimitRemaining);  // Requests left in window
console.log(client.generatedQuery);      // SQL from discover endpoints

​
Field Filtering

Control which fields are returned in the response. 
// Only return specific fields
const person = await client.person.enrich({
  email: 'jane@example.com',
  include_fields: 'full_name,job_title,company_name,linkedin_url',
});

// Exclude fields
const person2 = await client.person.enrich({
  email: 'jane@example.com',
  exclude_fields: 'phones,locations,education',
});

// Require fields (skip records missing these)
const person3 = await client.person.enrich({
  email: 'jane@example.com',
  required_fields: 'work_email,mobile_phone',
});

​
Error Handling

The SDK throws typed error classes for different error conditions. 
import DataLegion, {
  AuthenticationError,
  InsufficientCreditsError,
  ValidationError,
  RateLimitError,
  DataLegionError,
} from 'datalegion';

const client = new DataLegion({ apiKey: 'legion_...' });

try {
  const person = await client.person.enrich({ email: 'jane@example.com' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401 - Invalid or missing API key
    console.error('Check your API key');
  } else if (err instanceof InsufficientCreditsError) {
    // 402 - Out of credits
    console.error(`Out of credits: ${err.message}`);
  } else if (err instanceof ValidationError) {
    // 422 - Invalid request parameters
    console.error(`Invalid input: ${JSON.stringify(err.details)}`);
  } else if (err instanceof RateLimitError) {
    // 429 - Rate limit exceeded
    console.error(`Rate limited, retry after ${client.retryAfter}s`);
  } else if (err instanceof DataLegionError) {
    // Other API errors
    console.error(`API error (${err.statusCode}): ${err.message}`);
  }
}

​
Configuration

const client = new DataLegion({
  apiKey: 'legion_...',                     // Or set DATALEGION_API_KEY
  baseURL: 'https://api.datalegion.ai',          // Default
  timeout: 60000,                                // Milliseconds, default 60000
  defaultHeaders: {                              // Custom headers on all requests
    'X-Correlation-ID': 'my-request-123',
  },
});

​
TypeScript

The SDK is written in TypeScript and exports all request and response types. 
import DataLegion from 'datalegion';
import type {
  PersonResponse,
  PersonMatchesResponse,
  CompanyResponse,
  CompanyMatchesResponse,
  FieldCleanResponse,
  EmailHashResponse,
  ValidationResponse,
} from 'datalegion';

const client = new DataLegion({ apiKey: 'legion_...' });

// Return type is inferred based on multiple_results
const person: PersonResponse = await client.person.enrich({
  email: 'jane@example.com',
});

const matches: PersonMatchesResponse = await client.person.enrich({
  email: 'jane@example.com',
  multiple_results: true,
});

​
Resources