# DataRevIQ API

Pull your verified contacts into Clay, n8n, Zapier, your CRM or your own code. One key, three read-only endpoints. Reads are free.

- Base address: https://mcp.datareviq.io/functions/v1/api/v1
- Authentication: send your key as a bearer token in the Authorization header.
- Format: JSON.

A Resolution is a website visitor we identified, checked against your ideal customer profile and verified.

## Get a key

1. Open the app at https://app.datareviq.io and click API in the left menu.
2. Click Create key, name it and copy it. It starts with drq_live_. We show it once, so copy it now.
3. Only an account owner can create keys. If you are not the owner, ask the owner to create one for you.
4. Keep it private. Anyone who has it can read your contacts. You can revoke it in the app at any time.

## Send your key

Send it in the header on every request:

    Authorization: Bearer YOUR_KEY

The header X-API-Key: YOUR_KEY also works.

## GET /contacts

Returns your verified contacts.

Parameters:

| Name | Value | What it does |
|---|---|---|
| icp_fit | true | Only ICP Fit Resolutions |
| band | hot, warm or cold | Filter by intent |
| returned | true | Only people who came back |
| ready | true | Only contacts ready to contact (verified, with a deliverable business email) |
| since | ISO date | Only visits since this date |
| search | text | Match a name, company or title |
| limit | 1 to 100 | Contacts per request. Default 25 |
| offset | number | Where to start, for paging |

Example:

    curl "https://mcp.datareviq.io/functions/v1/api/v1/contacts?icp_fit=true&limit=25" \
      -H "Authorization: Bearer YOUR_KEY"

Response:

    {
      "data": [
        {
          "id": "...",
          "first_name": "...",
          "last_name": "...",
          "title": "...",
          "company": "...",
          "company_domain": "...",
          "company_linkedin_url": "...",
          "city": "...",
          "state": "...",
          "email": "...",
          "linkedin_url": "...",
          "verification_level": "business_verified",
          "icp_fit": true,
          "intent": "...",
          "score": 0,
          "pages_viewed": 0,
          "last_seen_at": "...",
          "returned": false,
          "stage": "..."
        }
      ],
      "total": 94,
      "limit": 25,
      "offset": 0
    }

Paging: add the limit to offset to get the next page. Stop when offset passes total.

verification_level is business_verified (identity confirmed from the LinkedIn profile) or email_verified (identity confirmed from the person's own email). Every contact has a deliverable business email. Personal emails are never returned for B2B accounts.

### Free accounts

The response also has a "locked" block with company-level entries:

    "locked": {
      "total": 12,
      "data": [
        {
          "id": "...",
          "locked": true,
          "company": "...",
          "company_domain": "...",
          "industry": "...",
          "seniority": "...",
          "department": "...",
          "icp_fit": true,
          "intent": "...",
          "pages_viewed": 0,
          "last_seen_at": "...",
          "freshness": "...",
          "returned": false
        }
      ],
      "unlock": { "cost_credits_per_contact": 1, "message": "...", "url": "https://app.datareviq.io" }
    }

The person's name and email unlock in the app with credits.

## GET /summary

Counts for your site. Optional parameter: since (ISO date).

    { "identified": 0, "icp_fit": 0, "ready_to_contact": 0, "high_intent": 0,
      "returned": 0, "needs_email": 0, "in_pipeline": 0, "customers": 0 }

## GET /credits

    { "balance": 0, "plan": "...", "trial_ends_at": null }

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 401 | The key is missing or wrong | Check the header. Create a new key if needed |
| 403 | The key cannot read | Create a new key |
| 429 | More than 60 requests in a minute | Wait 30 seconds, then retry |
| 503 | We could not answer | Retry in a few seconds |

## Limits

- 60 requests per minute for each key.
- Up to 100 contacts per request.
- A key works for one site.
- Read only today.

Questions: hello@datareviq.io
