API Reference

ClearView REST API v1

The ClearView API lets you programmatically access identified companies, ingest data from external sources, and receive webhook events. All endpoints use JSON and are served over HTTPS at https://app.democlearview.com/api/v1

# Authentication

Every API request must include a valid API key. You can create and manage keys in your Dashboard > Settings > API Keys page.

Sending your API key

Pass the key in one of two ways:

Method	Header	Example value
API Key header	X-Api-Key	cv_live_abc123...
Bearer token	Authorization	Bearer cv_live_abc123...

Permission levels

Level	Access
read	Read-only access to companies, visitors, and analytics
write	Everything in read, plus data ingestion and webhook management
admin	Full access including key management, settings, and billing

Creating an API key

1Go to Settings > API Keys in your ClearView dashboard.
2Click "Create New Key".
3Enter a label (e.g. "Production Backend") and choose a permission level.
4Copy the key immediately -- it will only be shown once.
5Store the key securely in environment variables or a secrets manager.

Keep your keys secret

Never commit API keys to version control or expose them in client-side code. Use environment variables and rotate keys regularly.

GET/api/v1/companies

Returns a paginated list of identified companies. Requires an API key with at least read permission.

Query parameters

Param	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
min_score	integer	--	Filter by minimum lead score (0-100)

Response body

Response 200

json

{
  "companies": [
    {
      "id": "comp_a1b2c3d4",
      "name": "Acme Corp",
      "domain": "acme.com",
      "industry": "Technology",
      "size": "51-200",
      "city": "San Francisco",
      "region": "California",
      "country": "US",
      "logoUrl": "https://logo.clearbit.com/acme.com",
      "linkedinUrl": "https://linkedin.com/company/acme",
      "employeeCount": 142,
      "revenue": "$10M-$50M",
      "leadScore": 87,
      "firstSeen": "2025-11-03T08:21:00Z",
      "lastSeen": "2025-12-15T14:33:12Z",
      "visitorCount": 12
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 347,
    "pages": 18
  }
}

Company object fields

Field	Type	Description
id	string	Unique company identifier
name	string	Company name
domain	string	Company website domain
industry	string	Industry classification
size	string	Company size range (e.g. "51-200")
city	string	City location
region	string	State or region
country	string	Country code (ISO 3166-1)
logoUrl	string \| null	URL to company logo
linkedinUrl	string \| null	LinkedIn company page URL
employeeCount	number \| null	Estimated employee count
revenue	string \| null	Estimated revenue range (e.g. "$10M-$50M")
leadScore	number	Computed lead score (0-100)
firstSeen	string	ISO 8601 timestamp of first visit
lastSeen	string	ISO 8601 timestamp of most recent visit
visitorCount	number	Number of unique visitors from this company

Examples

curl

bash

curl -X GET "https://app.democlearview.com/api/v1/companies?page=1&limit=10&min_score=50" \
  -H "X-Api-Key: cv_live_abc123your_key_here"

JavaScript (fetch)

javascript

const response = await fetch(
  "https://app.democlearview.com/api/v1/companies?page=1&limit=10&min_score=50",
  {
    headers: {
      "X-Api-Key": process.env.CLEARVIEW_API_KEY,
    },
  }
);
const data = await response.json();
console.log(data.companies);
console.log(`Page ${data.pagination.page} of ${data.pagination.pages}`);

Python (requests)

python

import requests
response = requests.get(
    "https://app.democlearview.com/api/v1/companies",
    params={"page": 1, "limit": 10, "min_score": 50},
    headers={"X-Api-Key": os.environ["CLEARVIEW_API_KEY"]},
)
data = response.json()
for company in data["companies"]:
    print(f"{company['name']} (score: {company['leadScore']})")

POST/api/v1/ingest

Batch-import companies, visitors, and page views from external sources. Requires a Bearer token with write or admin permission.

Authentication

This endpoint requires the Authorization: Bearer header (not X-Api-Key). Use a key with write or admin permissions.

Request body

json

{
  "companies": [
    {
      "name": "Acme Corp",
      "domain": "acme.com",
      "industry": "Technology",
      "size": "51-200"
    }
  ],
  "visitors": [
    {
      "ip": "203.0.113.42",
      "userAgent": "Mozilla/5.0 ...",
      "companyDomain": "acme.com"
    }
  ],
  "pageViews": [
    {
      "url": "/pricing",
      "visitorIp": "203.0.113.42",
      "timestamp": "2025-12-15T14:33:12Z",
      "duration": 45
    }
  ]
}

Response body

Response 200

json

{
  "success": true,
  "stats": {
    "created": 12,
    "updated": 3,
    "errors": 0
  }
}

Examples

curl

bash

curl -X POST "https://app.democlearview.com/api/v1/ingest" \
  -H "Authorization: Bearer cv_live_abc123your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {
        "name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Technology",
        "size": "51-200"
      }
    ],
    "visitors": [],
    "pageViews": []
  }'

JavaScript (fetch)

javascript

const response = await fetch("https://app.democlearview.com/api/v1/ingest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLEARVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    companies: [
      {
        name: "Acme Corp",
        domain: "acme.com",
        industry: "Technology",
        size: "51-200",
      },
    ],
    visitors: [],
    pageViews: [],
  }),
});
const result = await response.json();
console.log(`Created: ${result.stats.created}, Updated: ${result.stats.updated}`);

Python (requests)

python

import requests
import os
response = requests.post(
    "https://app.democlearview.com/api/v1/ingest",
    headers={
        "Authorization": f"Bearer {os.environ['CLEARVIEW_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "companies": [
            {
                "name": "Acme Corp",
                "domain": "acme.com",
                "industry": "Technology",
                "size": "51-200",
            }
        ],
        "visitors": [],
        "pageViews": [],
    },
)
result = response.json()
print(f"Created: {result['stats']['created']}, Updated: {result['stats']['updated']}")

POST/api/v1/webhook

Receive data from external services via webhook. ClearView automatically maps common field names to its internal schema. This is useful for connecting third-party tools that can send outgoing webhooks.

Authentication

Authenticate with either header:

Header	Description
X-Site-Key	Your ClearView site key (found in Settings > Tracking)
X-Webhook-Secret	A shared secret configured in Settings > Webhooks

Request body

Send any JSON object. ClearView auto-maps common field names:

Request body

json

{
  "company_name": "Acme Corp",
  "domain": "acme.com",
  "industry": "Technology",
  "employee_count": 142,
  "city": "San Francisco",
  "country": "US",
  "custom_field": "any additional data"
}

Auto-mapping

ClearView recognizes common field names like company_name, companyName, name, domain, website, and more. Fields that don't match a known mapping are stored as custom metadata.

Examples

curl

bash

curl -X POST "https://app.democlearview.com/api/v1/webhook" \
  -H "X-Site-Key: site_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Technology"
  }'

JavaScript (fetch)

javascript

const response = await fetch("https://app.democlearview.com/api/v1/webhook", {
  method: "POST",
  headers: {
    "X-Webhook-Secret": process.env.CLEARVIEW_WEBHOOK_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Acme Corp",
    domain: "acme.com",
    industry: "Technology",
  }),
});
const result = await response.json();
console.log(result);

Python (requests)

python

import requests
import os
response = requests.post(
    "https://app.democlearview.com/api/v1/webhook",
    headers={
        "X-Webhook-Secret": os.environ["CLEARVIEW_WEBHOOK_SECRET"],
        "Content-Type": "application/json",
    },
    json={
        "company_name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Technology",
    },
)
print(response.json())

# Rate Limits

Rate limits are applied per API key. When you exceed a limit, the API returns a 429 status code with a Retry-After header indicating how many seconds to wait.

Endpoint type	Limit
Read endpoints	100 requests / minute
Write endpoints	30 requests / minute
Ingest endpoint	10 requests / minute

Rate limit headers are included in every response:

Response headers

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1702656000

# Error Codes

All errors return a consistent JSON body:

Error response

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Status	Name	Description
400	Bad Request	Invalid request body or query parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
404	Not Found	Requested resource does not exist
409	Conflict	Resource already exists or version conflict
422	Unprocessable Entity	Request body validation failed
429	Too Many Requests	Rate limit exceeded. Check Retry-After header
500	Internal Server Error	Unexpected server error. Contact support if persistent

# Pagination

List endpoints return paginated results. The response includes a pagination object with the following fields:

Field	Type	Description
page	integer	Current page number
limit	integer	Items per page
total	integer	Total number of items
pages	integer	Total number of pages

To fetch all pages, increment the page parameter until page > pages:

Paginate all results

javascript

async function fetchAllCompanies(apiKey) {
  let allCompanies = [];
  let page = 1;
  let totalPages = 1;
  while (page <= totalPages) {
    const res = await fetch(
      `https://app.democlearview.com/api/v1/companies?page=${page}&limit=100`,
      { headers: { "X-Api-Key": apiKey } }
    );
    const data = await res.json();
    allCompanies = allCompanies.concat(data.companies);
    totalPages = data.pagination.pages;
    page++;
  }
  return allCompanies;
}

GET/api/v1/resolve

Resolve an IP address to a person and company, or look up all visitors from a specific domain. This is the same resolution engine that powers the ClearView dashboard and Chrome Extension.

Query parameters

Parameter	Type	Description
ip	string	IPv4 address to resolve to person + company
domain	string	Company domain to look up visitors and contacts

Provide one parameter

Pass either ip or domain, not both. IP resolution returns person-level data from the identity graph. Domain lookup returns all known visitors from that company.

Example: Resolve by IP

cURL

bash

curl -H "Authorization: Bearer cv_live_abc123..." \
  "https://democlearview.com/api/v1/resolve?ip=203.0.113.42"

Response

json

{
  "company": {
    "name": "Acme Corp",
    "domain": "acmecorp.com",
    "industry": "Technology",
    "employeeCount": 500,
    "revenue": "$50M - $100M"
  },
  "person": {
    "upId": "UP_001",
    "firstName": "Sarah",
    "lastName": "Chen",
    "businessEmail": "sarah@acmecorp.com",
    "jobTitle": "VP of Marketing",
    "seniority": "VP",
    "linkedinUrl": "https://linkedin.com/in/sarahchen"
  },
  "isBot": false
}

Example: Resolve by Domain

cURL

bash

curl -H "Authorization: Bearer cv_live_abc123..." \
  "https://democlearview.com/api/v1/resolve?domain=acmecorp.com"

Response

json

{
  "company": {
    "name": "Acme Corp",
    "domain": "acmecorp.com",
    "leadScore": 87,
    "pageViews": 42,
    "visitorCount": 5
  },
  "contacts": [
    {
      "firstName": "Sarah",
      "lastName": "Chen",
      "email": "sarah@acmecorp.com",
      "jobTitle": "VP of Marketing"
    }
  ]
}

# Watch List (Reverse Prospecting)

Upload target account domains to your watch list. When a visitor from a watched company hits your site, ClearView fires priority alerts via Slack, email, and webhooks (event: watchlist.hit).

GET/api/dashboard/watch-listList all watched domains

POST/api/dashboard/watch-listAdd domain(s) to watch list

DELETE/api/dashboard/watch-listRemove a domain from watch list

Add a single domain

POST body

json

{
  "domain": "google.com",
  "companyName": "Google",
  "notes": "Key target account - enterprise deal"
}

Bulk upload (CSV-style)

POST body

json

{
  "domains": ["google.com", "microsoft.com", "apple.com", "meta.com"]
}

# Outreach Drafts

ClearView automatically generates personalized outreach email drafts when a new contact is identified. Drafts are based on the contact's name, job title, company, and the pages they visited. High-intent visitors (pricing, demo pages) get more targeted messaging.

GET/api/dashboard/outreachList pending outreach drafts

POST/api/dashboard/outreachGenerate a draft for a specific contact

PATCH/api/dashboard/outreachMark draft as sent or dismissed

Example draft response

GET response

json

{
  "drafts": [
    {
      "id": "draft_abc123",
      "subject": "Quick question about Acme Corp's needs",
      "body": "Hi Sarah, I noticed someone from Acme Corp was looking at our pricing page...",
      "status": "pending",
      "contact": {
        "firstName": "Sarah",
        "lastName": "Chen",
        "email": "sarah@acmecorp.com",
        "jobTitle": "VP of Marketing",
        "company": { "name": "Acme Corp" }
      }
    }
  ]
}

# Cohort Insights

Aggregated analytics about your visitor traffic over the last 30 days. Use these insights to understand which industries visit most, which pages attract high-value leads, and when your traffic peaks.

GET/api/dashboard/insights

Response fields

Field	Description
topIndustries	Top 10 industries by visitor count
companySizeBreakdown	Distribution of visiting companies by size
topPagesByScore	Most viewed pages ranked by average lead score
topReferrers	Top 10 traffic sources (referrer domains)
dayOfWeekActivity	Page view count by day of week (Sun-Sat)

Need Help?

Having trouble with the API? Check the Troubleshooting guide or reach out to our support team.

Contact Support