# Data Hub Integration

## When to use

Use this skill whenever a task needs firmographic (company profile: industry, size, funding) or contact-level enrichment data, needs to check whether a domain or email already has a known company/contact profile, needs to search the company database by criteria (industry, employee count, country, funding stage, funding amount), needs to record a new signal or event against a company (e.g. a funding round, a hiring spike, a product launch you learned about), or needs to report on overall data coverage in Data Hub (data hub: the internal company/contact enrichment database). Do not use this skill for CRM (customer relationship management) record updates — route those to the microcrm skill instead.

## Tools

- `http-get` — read a single company or contact profile, run a company search, or fetch coverage stats
- `http-post` — bulk enrich domains/emails, or create a new company signal
- `http-request` — reserved for update/delete (PUT/PATCH/DELETE) operations; Data Hub currently exposes none, so do not use it against this app unless a new endpoint is confirmed
- `write-file` — stage large result sets (e.g. a multi-page company search or a bulk enrich response) to disk instead of holding them in context
- `send-message` — escalate to a human when authentication fails or the Integration is missing

## Playbook

1. To look up one company, call `http-get` against `/api/v1/companies/:domain`, substituting the bare domain (e.g. `acme.com`). This returns the company profile plus its latest funding info.
2. To look up one contact, call `http-get` against `/api/v1/contacts/:email` with the URL-encoded email address.
3. To search or filter companies, call `http-get` against `/api/v1/companies/search` with query params such as `industry`, `employee_count_range`, `country_code`, `funding_stage`, `operating_status`, `min_total_funding_usd`, or `name`. The response is paginated — follow the pagination cursor/page params until you have what you need, and if the result set is large, `write-file` it to a staging file rather than pasting it all into context.
4. To resolve many domains and/or emails at once (e.g. enriching a batch of leads), call `http-post` against `/api/v1/enrich` with a JSON body containing `domains` and/or `emails` arrays, each capped at 100 entries. Split larger batches into multiple calls. The response returns matching company and contact profiles keyed by the domain/email you sent.
5. To record a new event against a company (e.g. you learned about a funding round, a leadership change, or a product signal from another source), call `http-post` against `/api/v1/companies/:domain/signals` with a body containing `signal_type`, `occurred_at`, `title`, `body`, `url`, `source`, and an optional `raw` JSON payload.
6. To check overall data coverage before relying on Data Hub for a large task, call `http-get` against `/api/v1/stats`. This is cached for 5 minutes, so do not poll it more than once every few minutes.
7. Never fabricate a company or contact profile when a lookup returns no match — report the gap plainly (e.g. "no profile found for domain X") rather than guessing.

## Failure modes

- A 401 or 403 response means the API key configured on the org's Integration row for Data Hub is missing, invalid, or lacks scope. Stop immediately and use `send-message` to escalate to a human, naming "Data Hub" and stating that the API key/Integration needs to be checked or re-provisioned. Never retry with a guessed or hardcoded key.
- A missing Integration row (no Data Hub base URL configured for the org) should also be escalated via `send-message` rather than assumed or defaulted.
- A 422 on the signals endpoint usually means a required field (`signal_type`, `occurred_at`, or `title`) is missing or malformed — fix the payload and retry once; if it still fails, escalate.
- An enrich request exceeding 100 domains or 100 emails will fail — always chunk into batches of 100 or fewer before calling `http-post`.

## Done when

The requested company/contact profile, search result set, bulk enrichment, or signal creation has been retrieved or confirmed created, large result sets have been staged to disk via `write-file` when appropriate, and any authentication or missing-Integration failure has been escalated via `send-message` rather than silently abandoned.