People Enrichment (powered by OpenMerch)

Retrieve a full personal profile by Apollo person ID: full name, email address, LinkedIn URL, title, and employer. Use the id returned by openmerch-people-search as the lookup key.

Companion skill

Install openmerch-people-search alongside this skill for the full people-intelligence workflow. The two skills are designed to be used in tandem:

1. Search (openmerch-people-search) — find people at a company by domain and role keywords. Each result includes an id (Apollo person ID).
2. Enrich (this skill) — pass the id from step 1 to retrieve the full profile: email address, full name, LinkedIn URL, title, and employer.

If you already have an Apollo person ID from another source, you can run this skill standalone. Otherwise, run openmerch-people-search first to get the ID.

The exact price is confirmed by /v1/plan before anything runs. The skill never charges more than the planned max_cost. ClawHub does not handle billing and takes no fee — the charge is between you and OpenMerch.

Get a key from the Developer page in the OpenMerch app:

export OPENMERCH_API_KEY="om_live_xxxxxxxx"
# Optional — defaults to https://api.openmerch.dev:
# export OPENMERCH_BASE_URL="https://api.openmerch.dev"

Privacy & Acceptable Use

This skill returns sensitive personal data: full name, email address, and LinkedIn URL. Before running:

• Confirm you have a lawful basis to process this data (consent, legitimate interest, or another basis applicable in your jurisdiction).
• Store and share results only as required by your specific use case.
• Comply with GDPR, CCPA, and any other applicable privacy law.
• Do not use enriched data for unsolicited outreach, bulk profiling, or data brokering without authorization.

What this calls

No hidden network behavior. This skill makes only these OpenMerch HTTP calls, in order:

1. POST {OPENMERCH_BASE_URL}/v1/plan — confirm the job is executable and get the price.
2. POST {OPENMERCH_BASE_URL}/v1/execute — run the enrichment (one job).
3. GET {OPENMERCH_BASE_URL}/v1/jobs/{job_id} — only if the job is still executing, to poll until it finishes. Most runs return completed immediately and no polling is needed.

Every request sends the header X-OpenMerch-Key: $OPENMERCH_API_KEY.

How to run

Option A — reference script (deterministic)

Requires Node 18+ (no npm install):

node people-enrichment.mjs abc123

Prints a normalized JSON result to stdout and exits non-zero on error.

Option B — agent-driven (instructions)

1. Plan. POST /v1/plan:

{
  "job_type": "people_enrichment_v1",
  "input": {
    "operation": "people-enrichment",
    "params": {
      "id": "abc123"
    }
  }
}

• If can_execute is not true, stop and report the reason. Do not execute.
• Set max_cost = quoted_customer_price_microcents if present, otherwise estimated_cost.max_microcents. /v1/plan is the source of truth for the price — never hardcode one.

2. Execute. Generate one UUID v4 as idempotency_key. POST /v1/execute:

{
  "job_type": "people_enrichment_v1",
  "input": {
    "operation": "people-enrichment",
    "params": {
      "id": "abc123"
    }
  },
  "max_cost": "<max_cost from step 1>",
  "idempotency_key": "<uuid>"
}

Reuse the same idempotency_key on retry for the same lookup to prevent double charges. Generate a new key only for a genuinely new enrichment.

3. Poll only if needed. If status is "executing", poll GET /v1/jobs/{job_id} every ~1s (cap ~8 tries / ~15s) until status is completed, failed, or cancelled.

4. Report. On completed, present the normalized result (below). On failed/cancelled, report error.code and error.message. Always report job_id; include cost_usd when present.

curl equivalent

BASE="${OPENMERCH_BASE_URL:-https://api.openmerch.dev}"

curl -sS -X POST "$BASE/v1/plan" \
  -H "X-OpenMerch-Key: $OPENMERCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_type":"people_enrichment_v1","input":{"operation":"people-enrichment","params":{"id":"abc123"}}}'

Output

{
  "id": "abc123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "email_status": "verified",
  "title": "Senior Backend Engineer",
  "seniority": "senior",
  "linkedin_url": "https://www.linkedin.com/in/janedoe",
  "organization": "Stripe",
  "cost_usd": 0.008,
  "job_id": "…"
}

Always present: job_id.

Present when available: cost_usd (when the job returns cost data), plus all profile fields (id, first_name, last_name, email, email_status, title, seniority, linkedin_url, organization). Fields absent from the upstream response are omitted — never synthesized.

cost_usd is derived from cost.total_microcents (1 cent = 100,000 µ¢; $1.00 = 10,000,000).

Notes

• One enrichment per run. Input is a single Apollo person ID.
• The skill executes a single atomic OpenMerch job — no multi-step orchestration.
• Apollo person IDs are returned by openmerch-people-search in the id field of each result.