# DataMerge API — Quick Start

> Full documentation index: https://www.datamerge.ai/llms.txt
> Complete docs (all-in-one): https://www.datamerge.ai/docs/llms.txt

Get up and running with the DataMerge API in under 5 minutes.

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

**OpenAPI Schema:** `https://api.datamerge.ai/schema`

---

## Step 1: Get Your API Key

DataMerge accounts are set up by our team, so access starts with a conversation rather
than a signup form.

1. Contact us at https://www.datamerge.ai/contact
2. We discuss your use case and run a sample against your own data, so you can judge the
   data quality before committing
3. Once you go ahead, we create your account and add your credits
4. Log in at https://app.datamerge.ai, then go to **Account** and copy your API key

---

## Step 2: Authenticate

All requests need an API key header:

```
Authorization: Token YOUR_API_KEY
```

Incorrect or missing credentials return `401 Unauthorized`.

---

## Step 3: Enrich a Company

All enrichment is **asynchronous**: POST to start a job, then poll for results.

```bash
# Start enrichment
curl -X POST https://api.datamerge.ai/v1/company/enrich \
  -H "Authorization: Token $DATAMERGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

# Response:
# {"job_id": "abc123...", "status": "queued", ...}

# Poll until status is "completed" (usually a few seconds)
curl https://api.datamerge.ai/v1/company/enrich/abc123.../status \
  -H "Authorization: Token $DATAMERGE_API_KEY"

# Response when done:
# {"status": "completed", "record_ids": ["uuid1"], ...}

# Fetch the full company record (free — no credits charged)
curl "https://api.datamerge.ai/v1/company/get?record_id=uuid1" \
  -H "Authorization: Token $DATAMERGE_API_KEY"
```

**Key fields returned:** `legal_name`, `display_name`, `address1`, `city`, `region`, `country`, `country_code`, `industry_sic_name`, `group_employees`, `group_revenue`, `social_linkedin`, `social_x`, `datamerge_id`, `record_id`, `logo`, `year_started`, `global_ultimate_id`, `hierarchy_level`

---

## Step 4: Find Contacts

```bash
# Start contact search
curl -X POST https://api.datamerge.ai/v1/contact/search \
  -H "Authorization: Token $DATAMERGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com"],
    "max_results_per_company": 5,
    "job_titles": {
      "include": {
        "1": ["CEO", "CTO", "Chief Technology Officer"],
        "2": ["VP Engineering"]
      },
      "exclude": ["Intern", "Assistant"]
    },
    "location": {
      "include": [{"type": "country", "value": "United States"}]
    },
    "enrich_fields": ["contact.emails", "contact.phones"]
  }'

# Response: {"job_id": "...", "status": "queued", ...}

# Poll for results
curl https://api.datamerge.ai/v1/contact/search/JOB_ID/status \
  -H "Authorization: Token $DATAMERGE_API_KEY"

# Response when done: {"status": "completed", "record_ids": [...], ...}

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

**Note:** `max_results_per_company` goes at the top level of the request body. `job_titles.include` uses priority tiers (`"1"` is matched first). `location.include` is an array of `{type, value}` objects.

---

## Credit Costs

| Operation | Credits |
|-----------|---------|
| 1 company record | 1 credit |
| 1 contact with validated email | 1 credit |
| 1 mobile phone number | 4 credits |
| Fetching by record_id | 0 credits |
| Failed lookups | 0 credits |

**Evaluating DataMerge?** Contact us at https://www.datamerge.ai/contact and we will run a
sample against your own domains before you commit to anything.

Pricing is quoted against the volume you need, with no annual contract.

---

## Job Status Values

| Status | Meaning |
|--------|---------|
| `queued` | Accepted, waiting to start |
| `processing` | In progress |
| `completed` | Done — results available |
| `failed` | System error |

---

## Next Steps

- [Enrich Companies — full guide](https://www.datamerge.ai/docs/enrich-company.md)
- [Find Contacts — full guide](https://www.datamerge.ai/docs/find-contacts.md)
- [Full documentation (all-in-one)](https://www.datamerge.ai/docs/llms.txt)
- [OpenAPI Schema](https://api.datamerge.ai/schema)
- [Interactive Docs](https://api.datamerge.ai/docs)
- [Contact us](https://www.datamerge.ai/contact)