Enrichment API

Create a key in Settings → API keys (shown once). Send it as a bearer token on every request. Keys are hashed at rest and can be revoked anytime.

Authorization: Bearer de_live_xxxxxxxxxxxxxxxx

Enrich a company or contact. Live providers apply when your workspace is on a paid plan with provider keys configured; otherwise the response is mock-safe.

curl -X POST https://divineastromedia.com/api/v1/enrich \
  -H "Authorization: Bearer $DE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "type": "company", "input": { "domain": "intercom.com" } }'

{
  "ok": true,
  "data": {
    "jobId": "…",
    "company": { "name": "Intercom", "domain": "intercom.com", "industry": "software" },
    "contacts": [ { "fullName": "…", "title": "…", "email": "…", "grade": "B" } ],
    "contactsSuppressed": 0,
    "grade": "B", "riskClass": "YELLOW", "complianceAllowed": true
  }
}

contactsSuppressed reports how many results were withheld for compliance (opt-out / DNC / restricted source).

Enrich a single company by its public domain — the endpoint the Chrome extension uses. Domain only; social / login-walled hosts are rejected.

curl -X POST https://divineastromedia.com/api/v1/capture \
  -H "Authorization: Bearer $DE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "domain": "intercom.com" }'

Each key is limited to 60 requests/minute (HTTP 429 with Retry-After when exceeded). Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining so you can self-throttle. Every call is metered, and one prepaid credit is debited when a balance is available. Buy credit packs in Billing → API credits.

Subscribe an https endpoint in Settings → Webhooks to receive events (enrichment.completed, export.created, crm_sync.completed). Each delivery is signed with HMAC-SHA256 using your endpoint secret — verify it before trusting the payload:

// header: X-DataEnrich-Signature: sha256=<hex>
import crypto from "node:crypto";
const expected = "sha256=" + crypto
  .createHmac("sha256", endpointSecret)
  .update(rawRequestBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

This is also the substrate for Zapier / Make / n8n — point a webhook at your automation's catch hook.

401 invalid_api_key      missing / invalid / revoked / expired key
403 insufficient_scope   the key lacks the scope this route needs
422 validation_error     bad body, or Idempotency-Key reused with a different request
429 rate_limited         too many requests (see Retry-After)
402 arrears_cap_reached  prepaid credits exhausted past the daily arrears limit

Keys are least-privilege and can carry an expiry. Grant only what an integration needs: enrich:read (verify, score), enrich:write (enrich, extract, capture), export:write (build exports).

Send an Idempotency-Key header on credit-charging calls — a retry replays the original response without re-charging, and comes back with Idempotency-Replayed: true.

curl -X POST https://divineastromedia.com/api/v1/enrich \
  -H "Authorization: Bearer de_live_..." \
  -H "Idempotency-Key: order-4417" \
  -H "Content-Type: application/json" \
  -d '{"type":"company","input":{"domain":"acme.com"}}'

The full contract is machine-readable — generate a typed client, import it into Postman/Insomnia, or hand it to an AI agent.

# The spec
https://divineastromedia.com/api/v1/openapi.json

# Generate a typed TypeScript client
npx openapi-typescript https://divineastromedia.com/api/v1/openapi.json -o data-enrich.d.ts

View the raw spec →

The same capabilities are exposed to AI agents over the Model Context Protocol — so an assistant can enrich, verify, score, discover, and build compliance-safe exports on your behalf. Streamable HTTP with a bundled OAuth 2.1 authorization server (dynamic client registration, PKCE), scope-gated per tool.

Endpoint   https://divineastromedia.com/api/mcp
Transport  Streamable HTTP (spec 2025-11-25)
Auth       OAuth 2.1 (DCR + PKCE) — or a de_live_ key as a static bearer
Tools      enrich_company · enrich_contact · discover_companies
           verify_email · score_trust · build_export

Tools are registered only when the caller's scopes cover them, and workspace RBAC still applies — a read-only member can never export through an agent.

Every response runs through the same eligibility filter as exports and CRM sync. Records that are opted-out, on a do-not-contact list, blocked, or from a restricted source are removed before the API returns — so a data-subject request honored in the app is honored in the API on the very next call.