Data Hub Integration

skill

Read, create, and update Data Hub records through its REST API using an org Integration row.

Download .md

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.