API Overview - Data Legion

The Data Legion API provides programmatic access to our person and company data. Try for free with self-serve API access, or Contact Sales for enterprise agreements with premium fields and higher rate limits.

Base URL

https://api.datalegion.ai

Authentication

All requests require an API key passed via the API-Key header.

curl -X POST https://api.datalegion.ai/person/enrich \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -d '{"email": "jane.doe@example.com"}'

API keys are generated in your dashboard after signing up and being approved (most accounts within a couple of hours). Enterprise customers can Contact Sales for custom agreements.

Input Normalization

The enrichment API automatically normalizes inputs before matching, so you don’t need to clean your data first. Emails, phone numbers, names, URLs, and location fields are all normalized to canonical formats for consistent matching. For search endpoints, you can also use the Field Cleaning utility to clean and normalize fields before sending them to search.

Response Headers

Responses include these headers (Request-ID is on every response; the others may be absent on early rejections such as authentication failures, rate limits, and oversized payloads):

Header	Description
`Request-ID`	Unique request identifier for support and debugging — quote it when contacting support and we can trace the exact request
`Correlation-ID`	Echo of the `Correlation-ID` request header, if you sent one (up to 128 printable characters) — use it to tag requests with your own trace ids
`Process-Time`	Request processing time in seconds
`RateLimit-Policy`	Active rate limit policy (e.g. `100/min`)
`RateLimit-Limit`	Rate limit ceiling for your API key
`RateLimit-Remaining`	Requests remaining in current window
`RateLimit-Reset`	Unix timestamp when limit resets

Billed responses additionally include:

Header	Description
`Credits-Used`	Credits charged for this request
`Credits-Remaining`	Credits left on the contract that served the request
`Contract-ID`	Contract the request was billed against

Search and discover responses additionally include:

Header	Description
`Total-Count-Status`	`exact` when `total` is the full WHERE-clause cardinality; `estimate` when the exact count exceeded its time budget (broad, low-selectivity queries) and `total` is the query planner’s row estimate (a magnitude, not a precise figure); `page` when neither was available and `total` is just the size of the returned page

Errors

The API uses standard HTTP status codes and returns errors in a consistent JSON format:

{
  "error": "not_found",
  "message": "No person found matching the provided parameters."
}

Some errors include a details field with structured data for programmatic use:

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. This request requires up to 5 credits but only 2 are available.",
  "details": {
    "credits_required": 5,
    "credits_available": 2,
    "contact": "support@datalegion.ai"
  }
}

The details keys vary by error. For example, a 402 from an exhausted contract balance carries credits_remaining, expiration_date, and is_expired instead of credits_required/credits_available.

Status Codes

Code	Meaning
200	Success
400	Bad request: missing or invalid parameters
401	Unauthorized: invalid or missing API key
402	Insufficient credits: contract balance exhausted or expired
403	Forbidden: API key does not have access to this endpoint, or no active contract covers it
404	Not found: no matching record
408	Request timeout: the query exceeded the execution time limit
413	Payload too large: request body exceeds the size limit
422	Validation error: invalid field format
429	Rate limit exceeded
500	Internal server error
503	Service temporarily unavailable

Rate Limiting

Default rate limits vary by endpoint:

Endpoint	Rate Limit
`POST /person/enrich`	100 requests/min
`POST /person/search`	50 requests/min
`POST /person/discover`	50 requests/min
`POST /company/enrich`	100 requests/min
`POST /company/search`	50 requests/min
`POST /company/discover`	50 requests/min
`POST /utility/clean`	100 requests/min
`POST /utility/hash/email`	100 requests/min
`POST /utility/validate`	100 requests/min
`POST /utility/report/person`	50 requests/min
`POST /utility/report/company`	50 requests/min

Higher limits are available for enterprise customers. Contact sales to discuss your needs. When rate limited, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait.

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "details": {
    "limit": 50,
    "current": 51,
    "retry_after": 42
  }
}

Confidence Scores

Person match results and individual data points (emails, phones, locations, socials) include a confidence level:

Level	Description
high	Strong signals of accuracy
moderate	Good signals with some uncertainty
low	Limited signals, may need verification

Confidence is assigned by our proprietary scoring process. See Quality Scoring for usage guidance.

Company data does not include per-field confidence scores. Company records have a record-level num_sources count instead. See Company Data Overview for details.

Next Steps

Person Endpoints

Person Enrichment: Match records by email, phone, name, or social URL and append up to 100+ data points
Person Search: Query profiles using SQL-like syntax with flexible filtering
Person Discovery: Find people using natural language queries

Company Endpoints

Company Enrichment: Match companies by domain, name, LinkedIn, or ticker and append up to 50+ data points
Company Search: Query companies using SQL-like syntax with flexible filtering
Company Discovery: Find companies using natural language queries

Utilities

Field Cleaning: Normalize emails, phones, names, and other fields before sending to search
Email Hashing: Hash emails for privacy-safe enrichment via the email_hash parameter
Data Validation: Validate data format and get suggestions before sending to enrich or search

Data Schemas

Person Data Schema: Person schema reference with example record
Company Data Schema: Company schema reference with example record

​Base URL

​Authentication

​Input Normalization

​Response Headers

​Errors

​Status Codes

​Rate Limiting

​Confidence Scores

​Next Steps

​Person Endpoints

​Company Endpoints

​Utilities

​Data Schemas

Base URL

Authentication

Input Normalization

Response Headers

Errors

Status Codes

Rate Limiting

Confidence Scores

Next Steps

Person Endpoints

Company Endpoints

Utilities

Data Schemas