# Coldlytics in Clay (HTTP API columns)

Coldlytics is a database of US small and mid-sized businesses (local and trades businesses above all) and the people who run them: owners, founders, managers, with verified emails and direct dials. In Clay, add it as an **HTTP API** enrichment column (Growth plan or above) using the setups below.

One API key for every column: create it at https://app.coldlytics.com/dashboard/integrations/api-key with the scopes **search:read** (lookups) and **reveals:write** (emails and dials), then store it once in Clay as the header

    Authorization: Bearer cl_live_YOUR_KEY

Rules that make Coldlytics waterfall-friendly:

- A miss answers HTTP 200 with `found: false` and charges nothing, so the mapped output field is empty and Clay moves on to the next provider.
- Lookups (company by domain, person by email or LinkedIn URL) are free and allowed 120 requests per minute. Reveals and finds are allowed 30 per minute. Set the column's rate limit to **100 requests per 60,000 ms** for lookups and **25 per 60,000 ms** for reveals and finds; on a 429 Clay retries after the `Retry-After` header.
- Credits: 1 per email that verifies VALID when it is revealed (catch-all emails are delivered free), 1 per direct dial, 0 when the account already owns the person (so re-running a column never charges twice), 0 on every miss.
- Add a conditional run on every column, e.g. "only run if Domain is not empty", so blank rows cost nothing.

Full reference: https://api.coldlytics.com/docs (OpenAPI: https://api.coldlytics.com/v3/openapi.json).

## 1. Enrich a company by domain

- Method: GET
- URL: https://api.coldlytics.com/v3/companies/lookup
- Query parameter: `domain` = /Domain (a full website URL is fine)
- Headers: Authorization (above)

Outputs worth mapping (field paths):

| Path | Meaning |
|---|---|
| `data.found` | true / false |
| `data.company.name`, `data.company.categories` | Company name, business categories |
| `data.company.headcount`, `data.company.revenue`, `data.company.founded_year` | Size |
| `data.company.location_count`, `data.company.website.franchise` | Branches, franchise / national chain |
| `data.company.customer_type` | residential / commercial / both (trades) |
| `data.company.google.review_count`, `data.company.google.review_score`, `data.company.google.claimed` | Google Business Profile |
| `data.company.technologies`, `data.company.ad_pixels` | Website technologies, advertiser pixels |
| `data.company.website.website_grade`, `data.company.website.features`, `data.company.website.service_offerings` | Website quality (1-10), features (online booking, live chat, video, …), service model (free estimates, financing, 24/7, …) |
| `data.company.website.hiring.now`, `data.company.website.hiring.functions` | Hiring signal |
| `data.company.website.credentials`, `data.company.website.brands`, `data.company.website.languages` | Credentials, brands carried, languages |
| `data.company.website.ownership` | Self-declared ownership (family_owned, veteran_owned, women_owned, latino_owned, ...) |
| `data.company.website.read_at` | null means the website has not been read yet (signals unknown, not absent) |
| `data.locations[0].phone`, `data.locations[0].address.city`, `data.locations[0].address.state` | Primary location |
| `data.company.contact_count`, `data.people` | People on file (names, titles, has_email / has_dial; emails are revealed by column 5) |

## 2. Enrich a person by email

- Method: GET
- URL: https://api.coldlytics.com/v3/people/lookup
- Query parameter: `email` = /Email
- Outputs: `data.found`, `data.person.first_name`, `data.person.last_name`, `data.person.job_title`, `data.person.seniority`, `data.person.department`, `data.person.linkedin_url`, `data.person.location.city`, `data.person.location.state`, `data.person.has_dial`, `data.person.contact_id`, `data.company.name`, `data.company.domain`, `data.company.categories`, `data.company.phone`

Free. To get the person's direct dial, pass `data.person.contact_id` to column 5 with `include_dial` true.

## 3. Enrich a person by LinkedIn URL

Same as column 2 with the query parameter `linkedin_url` = /LinkedIn URL (any linkedin.com/in/… form).

## 4. Find a work email from name + domain

- Method: POST
- URL: https://api.coldlytics.com/v3/emails/find
- Headers: Authorization, `Content-Type: application/json`
- Body:

    {
      "first_name": "/First Name",
      "last_name": "/Last Name",
      "domain": "/Domain"
    }

- Outputs: `data.found`, `data.email`, `data.email_status` (VALID or CATCHALL), `data.source` (database or pattern), `data.job_title`, `data.linkedin_url`, `data.direct_dial`, `data.credits_charged`
- Cost: 1 credit when a VALID email is delivered; catch-all and misses free. Misses carry `data.reason` (company_unknown, pattern_unknown, catch_all_domain, not_verified, no_email, daily_limit).

## 5. Find the decision-maker at a domain and reveal their email

- Method: POST
- URL: https://api.coldlytics.com/v3/people/find
- Headers: Authorization, `Content-Type: application/json`
- Body (owners and founders first; drop `seniorities` to accept anyone on file, or add `"departments": ["MARKETING"]` / `"job_titles": ["manager"]`):

    {
      "domain": "/Domain",
      "seniorities": ["OWNERS_FOUNDERS", "DIRECTORS_EXECUTIVES"],
      "reveal": true,
      "include_dial": false
    }

- Outputs: `data.found`, `data.person.first_name`, `data.person.last_name`, `data.person.job_title`, `data.person.seniority`, `data.person.email`, `data.person.email_status`, `data.person.direct_dial`, `data.person.linkedin_url`, `data.person.credits_charged`, `data.alternates`
- Cost: 1 credit when a VALID email is delivered (plus 1 for a dial with `include_dial` true); at most one person is charged per row. `"reveal": false` only picks the person (free) and returns `data.person.contact_id` for a later reveal.
- To reveal a specific person from column 1 or 2 instead: POST https://api.coldlytics.com/v3/reveals with body `{"contact_id": /Contact Id, "include_dial": true}`; outputs `data.email`, `data.email_status`, `data.direct_dial`, `data.credits_charged`.

Questions: support@coldlytics.com