TypeScript client for the Data Legion API. Provides typed access to person enrichment, company enrichment, search, discovery, and utility endpoints.

• Zero external dependencies -- uses built-in fetch (Node.js 18+)
• Full TypeScript type definitions for all request and response objects
• Async-only API

Installation

npm install datalegion

Quick Start

import DataLegion from 'datalegion';

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

Or set the DATALEGION_API_KEY environment variable and omit the constructor argument:

const client = new DataLegion();

Person Enrichment

Look up a person by email, phone, social URL, name + location, or other identifiers.

const person = await client.person.enrich({ email: '[email protected]' });
console.log(person.full_name);
console.log(person.job_title, 'at', person.company_name);

Return multiple matches:

const results = await client.person.enrich({
  email: '[email protected]',
  multiple_results: true,
  limit: 2,
});

for (const match of results.matches) {
  console.log(match.person.full_name, '-', match.match_metadata?.match_confidence);
}

Person Search

Search for people using a SQL query.

const results = await client.person.search({
  query: "SELECT * FROM people WHERE company_name ILIKE '%google%'",
  limit: 10,
});

console.log(`Found ${results.total} people`);
for (const match of results.matches) {
  console.log(match.person.full_name, '-', match.person.job_title);
}

Person Discover

Search for people using natural language.

const results = await client.person.discover({
  query: 'engineers in San Francisco who worked at Google',
  limit: 10,
});

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

Company Enrichment

Look up a company by domain, name, LinkedIn ID, social URL, or ticker symbol.

const company = await client.company.enrich({ domain: 'google.com' });
console.log(company.name?.cleaned);
console.log(company.industry, '-', company.size);
console.log('Employees:', company.legion_employee_count);

Return multiple matches:

const results = await client.company.enrich({
  name: 'Google',
  multiple_results: true,
});

for (const match of results.matches) {
  console.log(match.company.name?.cleaned, '-', match.company.domain);
}

Company Search

Search for companies using a SQL query.

const results = await client.company.search({
  query: "SELECT * FROM companies WHERE industry = 'software development'",
  limit: 10,
});

for (const match of results.matches) {
  console.log(match.company.name?.cleaned, '-', match.company.domain);
}

Company Discover

Search for companies using natural language.

const results = await client.company.discover({
  query: 'AI companies with more than 100 employees',
  limit: 10,
});

for (const match of results.matches) {
  console.log(match.company.name?.cleaned);
}

Utility: Clean

Clean and normalise fields (email, phone, domain, name, etc.).

const cleaned = await client.utility.clean({
  fields: {
    email: '[email protected]',
    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}`);
}

Utility: Hash Email

Hash an email address (SHA-256, SHA-1, MD5).

const hashed = await client.utility.hashEmail({ email: '[email protected]' });
console.log(hashed.hashes.sha256);

Utility: Validate

Validate input data and receive errors, warnings, and suggestions.

const validation = await client.utility.validate({
  email: '[email protected]',
  phone: '+15551234567',
  company: 'Google LLC',
});

if (validation.valid) {
  console.log('All fields are valid');
} else {
  for (const err of validation.errors) {
    console.log(`${err.field}: ${err.error}`);
  }
}

Report a Data Issue

Report an inaccuracy in a person or company record against its legion_id. Free; see the docs for the issue_type/issue_level rules.

const report = await client.utility.reportPerson({
  legion_id: 'abc123',
  issue_type: 'incorrect',
  issue_level: 'field',
  field: 'job_title',
  observed_value: 'CEO',
  correct_value: 'CTO',
});
console.log(report.report_id, report.status);

Company records use client.utility.reportCompany() with the same parameters.

Health Check

const health = await client.health();
console.log(health.status); // "healthy"

Response Metadata

After each request, the client exposes metadata from response headers:

await client.person.enrich({ email: '[email protected]' });

console.log(client.requestId);           // unique request ID
console.log(client.creditsUsed);          // credits consumed
console.log(client.creditsRemaining);     // credits remaining
console.log(client.contractId);           // contract ID
console.log(client.rateLimitLimit);       // requests quota in current window
console.log(client.rateLimitRemaining);   // remaining requests in current window
console.log(client.rateLimitReset);       // unix timestamp when window resets
console.log(client.rateLimitPolicy);      // rate limit policy (e.g. "100/min")
console.log(client.retryAfter);           // seconds to wait (on 429 responses)
console.log(client.generatedQuery);       // SQL from discover endpoints
console.log(client.correlationId);        // echoed Correlation-ID

Error Handling

All API errors throw typed error classes that extend DataLegionError:

import { DataLegionError, AuthenticationError, RateLimitError } from 'datalegion';

try {
  await client.person.enrich({ email: '[email protected]' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key:', err.message);
  } else if (err instanceof RateLimitError) {
    console.error('Rate limited:', err.message);
  } else if (err instanceof DataLegionError) {
    console.error(`API error (${err.statusCode}):`, err.message);
  }
}

| Error Class | HTTP Status | Description | | -------------------------- | ----------- | -------------------------- | | AuthenticationError | 401 | Invalid or missing API key | | InsufficientCreditsError | 402 | Not enough credits | | ValidationError | 422 | Invalid request parameters | | RateLimitError | 429 | Too many requests | | DataLegionError | any | Base class for all errors |

Each error exposes statusCode, error, message, and details properties.

Configuration

const client = new DataLegion({
  apiKey: 'legion_...',       // required (or set DATALEGION_API_KEY env var)
  baseURL: 'https://api.datalegion.ai', // default
  timeout: 60000,                  // default: 60s
  defaultHeaders: {                // optional extra headers
    'X-Custom-Header': 'value',
  },
});

Documentation

Full API documentation is available at https://www.datalegion.ai/docs.