# 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


> 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`, `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

## 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

- [9 Best Company Data APIs in 2026](https://www.datamerge.ai/guides/best-company-data-apis): Comparison of the top company data APIs for CRM enrichment, outbound prospecting, AI agents, and RevOps workflows
- [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 & Access](#credit-costs--pricing) - how to get access and what credits cost
- [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)
- 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
- 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
- **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
- **Evaluation**: a sample run on your own data before you commit
- **Plans**: Quoted against the volume you need, with no annual contract or minimum commitment

### 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)

### 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. 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"
```

### 5. 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.

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

## Credit Costs & Pricing

**Getting access:** DataMerge accounts are set up by our team. Contact us at
https://www.datamerge.ai/contact and we will run a sample against your own data so you can
judge the quality before committing. Once you go ahead, we create your account, add your
credits, and you copy your API key from the Account page.

**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:**
- Quoted against the volume and markets you need
- No annual contract, no seat licensing, no minimum commitment
- 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*