# DataMerge — Complete Documentation (All-in-One)

> This file contains the **complete DataMerge documentation** inlined into a single page.
> Designed for AI agents and LLM tools that benefit from fetching all documentation in one request.
>
> - **This file:** https://www.datamerge.ai/docs/llms.txt
> - **Documentation index:** https://www.datamerge.ai/llms.txt
> - **AI Agents landing:** https://www.datamerge.ai/agents
> - **Skill file (AI agents):** https://www.datamerge.ai/SKILL.md
> - **OpenAPI Schema:** https://api.datamerge.ai/schema (also: https://www.datamerge.ai/openapi.yaml)
> - **Quick Start:** https://www.datamerge.ai/docs/quickstart.md
> - **Enrich Company guide:** https://www.datamerge.ai/docs/enrich-company.md
> - **Find Contacts guide:** https://www.datamerge.ai/docs/find-contacts.md
> - **Find Lookalikes guide:** https://www.datamerge.ai/docs/find-lookalikes.md


> B2B Company and Contact Data Enrichment Platform

DataMerge enriches company and contact data for B2B sales and marketing. Given a company domain, it returns the actual **legal entity** registered to that domain — including official legal name, registered address, jurisdiction, and position in the **corporate hierarchy**. For multinationals, you can retrieve any entity in the corporate tree: the country-level subsidiary, the regional parent, or the global ultimate holding company.

DataMerge also finds and enriches contacts at companies (emails, phones, LinkedIn). Covers 375M+ companies globally. Access via web application or REST API.

## MCP Server

DataMerge has a native MCP (Model Context Protocol) server for direct integration with AI coding tools:

- **Remote server:** `https://mcp.datamerge.ai` (streamable HTTP, no installation needed)
- **npm package:** `npm install @datamerge/mcp` (for local/stdio use)
- **GitHub:** https://github.com/poolside-ventures/datamerge-mcp
- **Setup guide:** https://www.datamerge.ai/docs/mcp.md

Compatible with Claude Desktop, Cursor, Windsurf, and any MCP client. Exposes all core operations as tools: `start_company_enrichment_and_wait`, `get_company_hierarchy`, `contact_search`, `start_lookalike`, `get_credits_balance`, and more.

## Machine-Readable Resources

- [Documentation](https://www.datamerge.ai/docs/llms.txt): **Complete documentation in a single file** — all endpoints, examples, data models, and workflows inlined (recommended for AI agents)
- [AI Agents](https://www.datamerge.ai/agents): Overview of all AI agent integration options — MCP, REST API, SKILL.md
- [SKILL.md](https://www.datamerge.ai/SKILL.md): Best practices and quick-start guide for AI coding agents integrating with the DataMerge API
- [OpenAPI Schema](https://api.datamerge.ai/schema): Full OpenAPI 3.0 specification (YAML) — also available at https://www.datamerge.ai/openapi.yaml
- [Interactive API Docs](https://api.datamerge.ai/docs): Redoc-rendered interactive documentation
- [Swagger UI](https://api.datamerge.ai/swagger): Swagger-rendered interactive documentation
- [Web Application](https://app.datamerge.ai): Full-featured UI for non-programmatic access

## Focused Guides

- [MCP Setup](https://www.datamerge.ai/docs/mcp.md): Connect DataMerge to Claude Desktop, Cursor, or Windsurf via MCP
- [Quick Start](https://www.datamerge.ai/docs/quickstart.md): Get your first enrichment running in 5 minutes
- [Enrich Company](https://www.datamerge.ai/docs/enrich-company.md): Deep dive — domains → firmographic profiles
- [Find Contacts](https://www.datamerge.ai/docs/find-contacts.md): Deep dive — contact search with job title and location filters
- [Find Lookalikes](https://www.datamerge.ai/docs/find-lookalikes.md): Deep dive — find similar companies to seed domains

## Website Pages

### Use Cases

- [B2B Sales Teams](https://www.datamerge.ai/use-cases/sales): Prospect enrichment, CRM data, warm introductions via hierarchy data, display vs legal name for outreach
- [Finance and Credit](https://www.datamerge.ai/use-cases/finance): Automated credit checks, KYB, fraud prevention, billing accuracy using verified legal names
- [Compliance and KYB](https://www.datamerge.ai/use-cases/compliance): Know Your Business verification, sanctions screening, conflict checks, vendor onboarding
- [Revenue Operations](https://www.datamerge.ai/use-cases/revops): CRM hygiene, territory design using hierarchy data, lead routing, deduplication
- [Procurement](https://www.datamerge.ai/use-cases/procurement): Vendor spend consolidation, supplier KYB, negotiation leverage via corporate hierarchy
- [AI Agents](https://www.datamerge.ai/use-cases/ai-agents): How LLM applications and autonomous agents use DataMerge

### Features

- [Legal Name Resolution](https://www.datamerge.ai/features/legal-name-resolution): How DataMerge resolves both the display name and the legal entity name from any domain
- [Company Hierarchy Data](https://www.datamerge.ai/features/company-hierarchy): Corporate hierarchy navigation, subsidiaries, parent companies, and global ultimate owner

### Guides

- [B2B Data Enrichment Guide](https://www.datamerge.ai/guides/b2b-data-enrichment-guide): What data enrichment is, why it matters, how enrichment waterfalls work
- [How to Find a Company's Legal Name from Its Website](https://www.datamerge.ai/guides/find-legal-name-from-website): Methods for resolving legal entity name from a domain
- [Company Hierarchy Data Explained](https://www.datamerge.ai/guides/company-hierarchy-data): What corporate hierarchy data is and why teams need it
- [Company Data Enrichment](https://www.datamerge.ai/guides/company-data-enrichment): Practical guide to enriching company records at scale
- [Contact Data Enrichment](https://www.datamerge.ai/guides/contact-data-enrichment): Finding and verifying B2B contact information
- [AI Agent Prompts](https://www.datamerge.ai/guides/ai-agent-prompts): 20 ready-to-use prompts for AI agents using DataMerge
- [How to Find a Company's Parent Company](https://www.datamerge.ai/guides/find-parent-company): Traverse corporate hierarchy to the global ultimate
- [How to Find Subsidiaries of a Company](https://www.datamerge.ai/guides/find-subsidiaries): Navigate corporate trees to find child entities
- [How to Identify a Company from Its Domain](https://www.datamerge.ai/guides/identify-company-from-domain): Resolve any website to its registered legal entity
- [Corporate Hierarchy Explained](https://www.datamerge.ai/guides/corporate-hierarchy-explained): What corporate hierarchies are and how to use them
- [Company Enrichment FAQ](https://www.datamerge.ai/guides/company-enrichment-faq): Common questions about company data enrichment

### Agent Resources

- [AI Agents Landing](https://www.datamerge.ai/agents): Overview of all AI agent integration options
- [SKILL.md](https://www.datamerge.ai/SKILL.md): Quick-start guide for AI coding agents
- [MCP Setup Guide](https://www.datamerge.ai/docs/mcp.md): Step-by-step MCP configuration

**API Base URL:** `https://api.datamerge.ai`

**Quick Navigation:**
- [Pricing & Free Trial](#credit-costs--pricing) - 20 free credits, no credit card required
- [Overview](#overview) - What DataMerge does
- [Core Features](#core-features) - Platform capabilities
- [Data Model](#data-model) - Record structures
- [API Endpoints](#api-endpoints) - REST API reference
- [Use Cases](#common-use-cases) - Examples and workflows
- [Getting Started](#getting-started) - Setup instructions

## Overview

**What it does:**
- Enrich company data from domain names (legal name, address, industry, employee count, revenue, social profiles)
- Return the specific legal entity registered to a domain, with full corporate hierarchy support
- Find and enrich business contacts (email, phone, LinkedIn)
- Discover company hierarchies (parent/subsidiary relationships, global ultimate ownership)
- Find lookalike companies using seed domains and firmographic filters
- Organize data in custom lists
- Integrate with HubSpot, Salesforce, or webhooks
- Process bulk operations via CSV upload

**Access methods:**
- Web Application: Interactive UI with guided workflows at https://app.datamerge.ai
- REST API: Programmatic access at https://api.datamerge.ai

**Key capabilities:**
- Legal entity data: Returns actual registered entities — `legal_name`, `country_code`, registered address, national ID
- Company hierarchy: Full corporate tree traversal via `/v1/company/hierarchy`
- Entity targeting: `country_code` param returns a specific country's subsidiary · `global_ultimate: true` returns the top holding company
- Asynchronous processing with job status polling
- Credit-based usage with transparent pricing
- Self-serve access: 20 free leads to start, flexible pay-as-you-go or subscription plans

## Core Features

### Company Enrichment
- **Domain-to-Company Enrichment**: Convert domain names into comprehensive legal entity profiles
- **Legal Entity Data**: Returns official legal name, registered address, national company ID, and jurisdiction
- **Multi-Method Lookup**: Uses multiple data sources for maximum accuracy
- **Company Hierarchy**: Discover parent companies and subsidiaries with global ultimate tracking
- **Entity Targeting**: Retrieve a specific country's subsidiary or the global ultimate holding company
- **Lookalike Discovery**: Find similar companies based on seed domains and firmographic filters
- **Batch Processing**: Enrich multiple domains in one request or via CSV upload

### Contact Enrichment & Search
- **Contact Search**: Find contacts at companies with filters:
  - Job titles (include with priority tiers / exclude)
  - Location (country, region, city with include/exclude)
  - Max results per company
- **Contact Enrichment**: Enrich contacts with email, phone, and LinkedIn data via LinkedIn URL or name+domain
- **Deduplication**: Automatic prevention of duplicate contacts in your lists

### List Management
- **Flexible Lists**: Create and manage custom lists for companies and contacts
- **List Operations**: Add items during enrichment, remove items, delete lists
- **System Lists**: Automatic "Uncategorized" and "Deleted" lists
- **Pagination & Sorting**: Efficiently browse large lists

### Credit System
- **Credit-Based Usage**: Transparent credit consumption per operation
- **Free Trial**: 20 credits on signup, no credit card required
- **Plans**: Monthly subscriptions from $15/month, pay-as-you-go, annual discount

### Async Processing
- **Asynchronous Jobs**: All enrichment operations run asynchronously
- **Status Values**: `queued` → `processing` → `completed` or `failed`
- **Record IDs**: Completed jobs return `record_ids` — fetch each via GET endpoints (free)

## Data Model

### Company Record Fields
- `datamerge_id`: Unique DataMerge company identifier (e.g. `DM001283124635`)
- `record_id`: User-specific record UUID
- `domain`: Primary company domain
- `legal_name`: Official registered legal name
- `display_name`: Common trading / brand name
- `year_started`: Year founded (string)
- `address1`, `address2`: Street address lines
- `city`: City
- `province`: Province or state
- `region`: Region / state
- `post_code`: Postal / ZIP code
- `country`: Country name
- `country_code`: ISO-2 country code
- `longitude`, `latitude`: Geo coordinates (strings)
- `group_employees`: Employee band string (e.g. `"10,001+ employees"`)
- `group_revenue`: Revenue band string (e.g. `"500-1000M USD"`)
- `group_companies`: Number of entities in corporate group (integer)
- `industry_sic_code`, `industry_sic_name`: SIC industry classification
- `industry_nace_code`, `industry_nace_name`: NACE industry classification
- `national_id`: National company registration number
- `national_id_type`: Type of national ID (e.g. `"US Business Registration Number"`)
- `social_linkedin`: LinkedIn URL
- `social_facebook`: Facebook URL
- `social_x`: X / Twitter URL
- `parent_id`: DataMerge ID of the direct parent company
- `global_ultimate_id`: DataMerge ID of the global ultimate holding company
- `global_ultimate_name`: Name of the global ultimate holding company
- `hierarchy_level`: Position in corporate hierarchy (0 = global ultimate)
- `logo`: Company logo URL
- `status`: `success`, `not_found`, `no_query_match`, `pending`

### Contact Record Fields
- `record_id`: Unique contact UUID
- `linkedin_url`: LinkedIn profile URL
- `linkedin_handle`: LinkedIn handle
- `sales_navigator_id`: LinkedIn Sales Navigator ID
- `firstname`, `lastname`: Contact name
- `email`: Primary email address
- `email_status`: Email validation status (`valid`, `HIGH_PROBABILITY`, etc.)
- `phone`: Primary phone number
- `city`, `region`, `country`, `country_code`: Location
- `headline`: Professional headline
- `title`: Job title
- `company_domain`: Company domain
- `company_display_name`: Company name
- `company_id`: DataMerge company ID
- `company_group`: Global ultimate company ID
- `status`: `success`, `pending`, `not_found`
- `credits_consumed`: Credits charged for this record

### List Record Fields
- `id`: Unique list UUID
- `name`: User-defined name
- `slug`: URL-safe identifier (used in API paths)
- `list_type`: `user`, `import`, `uncategorized`, `deleted`
- `object_type`: `company` or `contact`
- `count`: Number of items
- `is_system`: System-managed flag

## Web Application Routes

- `/quick-start` - Guided dashboard for all operations
- `/companies` or `/companies/{list-slug}` - Company list management
- `/contacts` or `/contacts/{list-slug}` - Contact list management
- `/csv-upload` - Bulk upload with analysis and history
- `/integrations` - Manage webhooks and CRM connections
- `/billing` - Purchase credits and manage subscriptions
- `/logs` - Operation logs and audit trail
- `/account` - API key and account settings

## API Endpoints

**Base URL:** `https://api.datamerge.ai`

**Full OpenAPI spec:** https://api.datamerge.ai/schema

### Authentication
All API requests require an API key:
```
Authorization: Token <your_api_key>
```

Incorrect or missing credentials return `401 Unauthorized`.

**Rate Limits**: 1000 requests/hour for authenticated users

### Company API

#### Enrich Company
```
POST /v1/company/enrich
```
Enrich one or more companies by domain. Returns a `job_id` (async).

Single domain:
```json
{"domain": "stripe.com"}
```

Batch:
```json
{
  "domains": ["stripe.com", "shopify.com"],
  "country_code": ["US"],
  "global_ultimate": false,
  "list": "my-companies",
  "skip_if_exists": true
}
```

Response (202):
```json
{"job_id": "abc123...", "type": "company_enrich", "status": "queued", "total_domains": 1, "valid_domains": 1}
```

#### Get Enrichment Status
```
GET /v1/company/enrich/{job_id}/status
```
Poll until `status` is `"completed"` or `"failed"`. Response includes `record_ids`.

Status values: `queued` · `processing` · `completed` · `failed`

#### Get Company
```
GET /v1/company/get?datamerge_id={id}
GET /v1/company/get?record_id={uuid}
```
Provide either `datamerge_id` (charges 1 credit) or `record_id` (free). Not both.

Optional: `add_to_list` — list slug to add the company to (only with `datamerge_id`).

#### Company Hierarchy
```
GET /v1/company/hierarchy?datamerge_id={id}
```
Get all entities in the same global ultimate hierarchy.

Parameters: `include_names` (bool, charges 1 credit), `include_branches` (bool), `only_subsidiaries` (bool), `max_level` (int), `country_code` (array), `page` (int)

#### Find Lookalike Companies
```
POST /v1/company/lookalike
```
Find similar companies using seed domains. Returns a `job_id` (async, 202).

```json
{
  "companiesFilters": {
    "lookalikeDomains": ["stripe.com"],
    "primaryLocations": {"includeCountries": ["us", "gb"]},
    "companySizes": ["51-200", "201-500"],
    "revenues": ["10-50M", "50-100M"],
    "yearFounded": {"min": 2005, "max": 2020}
  },
  "size": 50,
  "list": "target-accounts",
  "exclude_all": false
}
```

Response (202):
```json
{"job_id": "abc123...", "status": "queued", "message": "Lookalike batch started..."}
```

#### Lookalike Status
```
GET /v1/company/lookalike/{job_id}/status
```
Poll until `status` is `"completed"` or `"failed"`. Response includes `record_ids`.

### Contact API

#### Search for Contacts
```
POST /v1/contact/search
```
Search for contacts at specified companies. Returns a `job_id` (async, 202).

```json
{
  "domains": ["stripe.com", "shopify.com"],
  "max_results_per_company": 5,
  "job_titles": {
    "include": {
      "1": ["CEO", "CTO", "Chief Technology Officer"],
      "2": ["VP Engineering", "VP of Engineering"]
    },
    "exclude": ["Intern", "Assistant"]
  },
  "location": {
    "include": [{"type": "country", "value": "United States"}],
    "exclude": []
  },
  "enrich_fields": ["contact.emails", "contact.phones"],
  "webhook": "https://your-app.com/webhook"
}
```

Key notes:
- `max_results_per_company` is at the **top level** of the request body
- `job_titles.include` uses priority tiers: `"1"` is matched before `"2"`
- `location.include` is an array of `{type, value}` objects (type: `country`, `region`, or `city`)
- `enrich_fields` is required (at least one of `contact.emails` or `contact.phones`)

Use `company_list` (slug) instead of `domains` to search a saved list.

#### Contact Search Status
```
GET /v1/contact/search/{job_id}/status
```
Poll until `status` is `"completed"` or `"failed"`. Response includes `record_ids`.

#### Enrich Contacts
```
POST /v1/contact/enrich
```
Enrich specific contacts by LinkedIn URL or name+domain. Returns a `job_id` (async, 202).

```json
{
  "contacts": [
    {"linkedin_url": "https://www.linkedin.com/in/johndoe"},
    {"firstname": "Jane", "lastname": "Smith", "domain": "stripe.com"}
  ],
  "enrich_fields": ["contact.emails", "contact.phones"]
}
```

#### Contact Enrichment Status
```
GET /v1/contact/enrich/{job_id}/status
```
Poll until `status` is `"completed"` or `"failed"`. Response includes `record_ids`.

#### Get Contact
```
GET /v1/contact/get?record_id={uuid}
```
Retrieve a specific contact by record UUID. Never charges credits.

### Lists API

#### Get All Lists
```
GET /v1/lists
GET /v1/lists?object_type=company
GET /v1/lists?object_type=contact
```

#### Create List
```
POST /v1/lists
```
```json
{"name": "Target Accounts", "object_type": "company"}
```

#### Get List Items
```
GET /v1/lists/{object_type}/{list_slug}
```
`object_type`: `company` or `contact`. `list_slug`: the list's slug (e.g. `target-accounts`).

Parameters: `page`, `page_size` (max 100), `sort_by`, `sort_order` (`asc`/`desc`)

#### Remove Item from List
```
DELETE /v1/lists/{object_type}/{list_slug}/{item_id}
```

#### Delete List
```
DELETE /v1/lists/{object_type}/{list_slug}
```
System lists cannot be deleted.

### Account API

#### Credits Balance
```
GET /v1/credits/balance
```
```json
{
  "credits_balance": 5440,
  "balances": {"one_off": 5440, "recurring": 0, "rollover": 0, "total": 5440}
}
```

## Common Use Cases

### 1. Enrich a Single Company
```bash
# Start job
curl -X POST https://api.datamerge.ai/v1/company/enrich \
  -H "Authorization: Token $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

# Poll status
curl https://api.datamerge.ai/v1/company/enrich/JOB_ID/status \
  -H "Authorization: Token $KEY"

# Fetch record (free)
curl "https://api.datamerge.ai/v1/company/get?record_id=RECORD_ID" \
  -H "Authorization: Token $KEY"
```

### 2. Find Contacts at Multiple Companies
```bash
curl -X POST https://api.datamerge.ai/v1/contact/search \
  -H "Authorization: Token $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com", "shopify.com"],
    "max_results_per_company": 5,
    "job_titles": {
      "include": {"1": ["CEO", "CTO"], "2": ["VP Engineering"]}
    },
    "location": {
      "include": [{"type": "country", "value": "United States"}]
    },
    "enrich_fields": ["contact.emails", "contact.phones"]
  }'
```

### 3. Create a List and Add Companies

```bash
# Create list
curl -X POST https://api.datamerge.ai/v1/lists \
  -H "Authorization: Token $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Target Companies", "object_type": "company"}'

# Enrich with list assignment
curl -X POST https://api.datamerge.ai/v1/company/enrich \
  -H "Authorization: Token $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["stripe.com", "shopify.com"], "list": "target-companies"}'
```

### 4. Find Lookalike Companies
```bash
curl -X POST https://api.datamerge.ai/v1/company/lookalike \
  -H "Authorization: Token $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companiesFilters": {
      "lookalikeDomains": ["stripe.com"],
      "primaryLocations": {"includeCountries": ["us"]},
      "companySizes": ["51-200", "201-500", "501-1000"]
    },
    "size": 50
  }'
# Then poll /v1/company/lookalike/JOB_ID/status
```

### 5. Lookalike → Contacts (Full Pipeline)

```python
import requests, time

headers = {"Authorization": f"Token {api_key}"}

# Step 1: Find lookalikes
r = requests.post("https://api.datamerge.ai/v1/company/lookalike",
    headers=headers, json={
        "companiesFilters": {
            "lookalikeDomains": ["stripe.com"],
            "primaryLocations": {"includeCountries": ["us"]},
            "companySizes": ["51-200", "201-500"]
        },
        "size": 30
    })
job_id = r.json()["job_id"]

# Step 2: Poll lookalike status
while True:
    r = requests.get(f"https://api.datamerge.ai/v1/company/lookalike/{job_id}/status",
        headers=headers)
    data = r.json()
    if data["status"] in ("completed", "failed"):
        break
    time.sleep(5)

# Step 3: Fetch domains (free)
domains = []
for record_id in data.get("record_ids", []):
    c = requests.get(f"https://api.datamerge.ai/v1/company/get?record_id={record_id}",
        headers=headers).json()
    if c.get("record", {}).get("domain"):
        domains.append(c["record"]["domain"])

# Step 4: Find contacts
r = requests.post("https://api.datamerge.ai/v1/contact/search",
    headers=headers, json={
        "domains": domains,
        "max_results_per_company": 3,
        "job_titles": {"include": {"1": ["CEO", "VP Sales", "Head of Sales"]}},
        "enrich_fields": ["contact.emails"]
    })
search_job_id = r.json()["job_id"]

# Step 5: Poll contact search
while True:
    r = requests.get(f"https://api.datamerge.ai/v1/contact/search/{search_job_id}/status",
        headers=headers)
    data = r.json()
    if data["status"] in ("completed", "failed"):
        break
    time.sleep(3)

# Step 6: Fetch contacts (free)
for record_id in data.get("record_ids", []):
    contact = requests.get(f"https://api.datamerge.ai/v1/contact/get?record_id={record_id}",
        headers=headers).json()
    print(contact["record"]["email"])
```

### 6. Company Hierarchy — Find All Subsidiaries
```bash
# Get all entities in Alphabet Inc.'s corporate tree
curl "https://api.datamerge.ai/v1/company/hierarchy?datamerge_id=DM001202164930&include_names=true" \
  -H "Authorization: Token $KEY"

# Get only UK entities
curl "https://api.datamerge.ai/v1/company/hierarchy?datamerge_id=DM001202164930&country_code=GB&include_names=true" \
  -H "Authorization: Token $KEY"
```

### 7. Set Up Webhook Integration

Configure a webhook URL in the web app at https://app.datamerge.ai/integrations, or pass `"webhook": "https://your-app.com/endpoint"` in any enrich or search request.

### 8. CSV Bulk Enrichment (Web App)
Upload CSV → Review analysis (duplicates, invalid entries, credit cost) → Confirm → Monitor progress → Export results

## Credit Costs & Pricing

**Free Trial — Start immediately, no credit card required:**
- Sign up at https://app.datamerge.ai → verify email → **get 20 free credits**

**Credit Costs:**
- 1 credit = 1 company record or 1 contact with validated email
- 4 credits = 1 mobile phone number
- 1 credit = `GET /v1/company/get?datamerge_id=...` (lookup by DataMerge ID)
- 0 credits = failed lookups — you only pay for successful results
- 0 credits = `GET /v1/company/get?record_id=...` or `GET /v1/contact/get` (your existing records)

**Paid Plans:**
- Monthly subscriptions from **$15/month**
- Pay-as-you-go credit packs (no ongoing commitment)
- Annual plans: 20% discount
- Multi-currency: USD, EUR, GBP

Full pricing: https://www.datamerge.ai/pricing

## Record Status Values

### Company Record Status
- `success`: Successfully enriched with full data
- `not_found`: Domain valid but not in database — no credits charged
- `no_query_match`: Company found but didn't match your country filters — no credits charged
- `pending`: Still processing

### Contact Record Status
- `success`: Successfully enriched (email and/or phone found)
- `pending`: Enrichment in progress
- `not_found`: Contact found but no enrichment data available — no credits charged

### Job Status
- `queued`: Accepted, waiting to start
- `processing`: Currently executing
- `completed`: Finished successfully — `record_ids` available
- `failed`: Job failed due to system error

## CSV Format Requirements

### Company CSV Upload
- **Format**: One domain per line, no headers
- **Encoding**: UTF-8
- **Max Records**: 10,000 domains per file
- **Max File Size**: 10MB

### Example Valid CSV
```
microsoft.com
google.com
stripe.com
shopify.com
```

### CSV Analysis Features
Before processing, the system shows: total domains, valid/invalid counts, duplicate detection, and estimated credit cost.

## Best Practices

- **Async pattern**: POST → get `job_id` → poll status → collect `record_ids` → GET each record (free)
- **Batch operations**: Pass `domains` array (not individual requests) for multiple companies
- **Skip duplicates**: Use `skip_if_exists: true` when adding to a list to avoid charging credits for already-enriched domains
- **Record retrieval is free**: `GET /v1/company/get?record_id=...` and `GET /v1/contact/get` never charge credits
- **Job title tiers**: Use `"1"` for primary titles, `"2"` for secondary — broader tier 2 increases match rate
- **List slugs in paths**: Lists are referenced by `slug` (e.g. `target-accounts`) in URL paths, not by UUID
- **Rate limits**: 1000 requests/hour for authenticated users

## Support & Documentation

- **Web Application**: https://app.datamerge.ai
- **API Base URL**: https://api.datamerge.ai
- **Interactive API Docs (Redoc)**: https://api.datamerge.ai/docs
- **Swagger UI**: https://api.datamerge.ai/swagger
- **OpenAPI Schema (YAML)**: https://api.datamerge.ai/schema
- **Support**: https://www.datamerge.ai/contact

---

**DataMerge** - Enrich your B2B data with confidence.

*Dual-interface platform: Full-featured web application + comprehensive REST API*