> ## Documentation Index
> Fetch the complete documentation index at: https://www.datalegion.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Overview of the Data Legion API: authentication, base URL, rate limits, and getting started with programmatic access to person and company data.

The Data Legion API provides programmatic access to our person and company data. [Try for free](https://www.datalegion.ai/sign-up) with self-serve API access, or [Contact Sales](https://www.datalegion.ai/get-started) for enterprise agreements with premium fields and higher rate limits.

## Base URL

```text theme={null}
https://api.datalegion.ai
```

## Authentication

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

```bash theme={null}
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](https://www.datalegion.ai/sign-up) and being approved (most accounts within a couple of hours). Enterprise customers can [Contact Sales](https://www.datalegion.ai/get-started) 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](/docs/api-reference/utility-clean) 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:

```json theme={null}
{
  "error": "not_found",
  "message": "No person found matching the provided parameters."
}
```

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

```json theme={null}
{
  "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](https://www.datalegion.ai/get-started) to discuss your needs.

When rate limited, the API returns HTTP 429 with a `Retry-After` header indicating how many seconds to wait.

```json theme={null}
{
  "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](/docs/data-quality/quality-scoring) for usage guidance.

<Note>
  Company data does not include per-field confidence scores. Company records have a record-level `num_sources` count instead. See [Company Data Overview](/docs/company-data/overview) for details.
</Note>

## Next Steps

### Person Endpoints

* **[Person Enrichment](/docs/api-reference/person-enrichment)**: Match records by email, phone, name, or social URL and append up to 100+ data points
* **[Person Search](/docs/api-reference/person-search)**: Query profiles using SQL-like syntax with flexible filtering
* **[Person Discovery](/docs/api-reference/person-discovery)**: Find people using natural language queries

### Company Endpoints

* **[Company Enrichment](/docs/api-reference/company-enrichment)**: Match companies by domain, name, LinkedIn, or ticker and append up to 50+ data points
* **[Company Search](/docs/api-reference/company-search)**: Query companies using SQL-like syntax with flexible filtering
* **[Company Discovery](/docs/api-reference/company-discovery)**: Find companies using natural language queries

### Utilities

* **[Field Cleaning](/docs/api-reference/utility-clean)**: Normalize emails, phones, names, and other fields before sending to search
* **[Email Hashing](/docs/api-reference/utility-hash-email)**: Hash emails for privacy-safe enrichment via the `email_hash` parameter
* **[Data Validation](/docs/api-reference/utility-validate)**: Validate data format and get suggestions before sending to enrich or search

### Data Schemas

* **[Person Data Schema](/docs/person-data/schema)**: Person schema reference with example record
* **[Company Data Schema](/docs/company-data/schema)**: Company schema reference with example record