For AI agents

Copy this to your agent

You are setting up programmatic access to Uniqueness Engine (https://uniquenessengine.com) — an API that takes a LinkedIn URL and returns a fact-checked Connection Brief. Every fact carries a source link and the quote it came from. Broader interest signals and the personality read are clearly marked as a read, not a fact. Profiles are read from multiple independent public-data providers with automatic fallback; if fewer than 3 personal facts verify, additional verified public-source lanes engage automatically. Every candidate must pass the same identity and fact checks. Follow these steps in order. Where marked [ASK USER], stop and get input from the person you're working for before continuing — do not guess or fabricate that input.

1) SIGN UP — named email verification. Keep both returned values in this trusted process; they are secrets, but neither is an API key.
   SIGNUP_RESPONSE="$(curl -sS -X POST https://uniquenessengine.com/api/signup \
     -H 'content-type: application/json' \
     -d '{"email":"[ASK USER for their email]","client_name":"[ASK USER for a client name]","device_name":"[ASK USER for a device name]"}')"
   If signup returns HTTP 503 with error "verification_delivery_failed", no usable polling secret or API key was issued. Honor Retry-After, then repeat this signup request.
   TRANSACTION_ID="$(printf '%s' "$SIGNUP_RESPONSE" | jq -r '.transaction_id')"
   POLLING_TOKEN="$(printf '%s' "$SIGNUP_RESPONSE" | jq -r '.polling_token')"
   Do not print, email, log, or put the polling token in an agent transcript. Approval creates a new revocable API key once; it grants no free live credits.

2) VERIFY, CLAIM ONCE, then store the key in a secret manager or trusted environment.
   A human approves the named device from their email. Poll with BOTH retained values until status is "approved":
   curl -sS "https://uniquenessengine.com/api/signup/verification/$TRANSACTION_ID" \
     -H "x-verification-token: $POLLING_TOKEN"
   Pending, denied, expired, and already_claimed do not yield a key. Only after approved, call this exactly once:
   CLAIM_RESPONSE="$(curl -sS -X POST "https://uniquenessengine.com/api/signup/verification/$TRANSACTION_ID/claim" \
     -H "x-verification-token: $POLLING_TOKEN")"
   export UNIQUENESS_API_KEY="$(printf '%s' "$CLAIM_RESPONSE" | jq -r '.api_key')"
   Never echo or relay the key to the user/agent transcript. Then verify the account:
   curl https://uniquenessengine.com/api/account -H "authorization: Bearer $UNIQUENESS_API_KEY"
   This confirms total spendable credit and provenance.

2a) SEE A CONNECTION BRIEF INSTANTLY — free example fixture, no key, no credits.
   Run this before asking the user for their own LinkedIn URL. It returns a hand-authored synthetic showcase persona ("Jordan Ellis") that shows the full response shape — no auth, no charge, no polling:
   curl https://uniquenessengine.com/api/examples/kitchen-sink
   Expected: HTTP 200 with a brief that has "mode":"synthetic_fixture", "not_a_real_person":true, identity.full_name, safe_to_reference[] (each with evidence_quote + source_url), personality, and a capabilities block. It defaults to the full shape; add ?detail=compact for the compact shape. This is a fixture, never a real resolution — real lookups run through /api/enrich (step 3).

3) TEST the user's own real LinkedIn URL. [ASK USER] for the LinkedIn URL unless they already gave one. A fresh brief usually runs 45-90s (rarely up to ~3 min), so the API is ASYNCHRONOUS: submit, then poll.
   Submit:
   curl -X POST https://uniquenessengine.com/api/enrich \
     -H "authorization: Bearer $UNIQUENESS_API_KEY" \
     -H 'content-type: application/json' \
     -d '{"linkedin_url":"[ASK USER for their LinkedIn URL]"}'
   This returns 202 {"job_id":"...","status":"queued"} (or 200 {"status":"done","brief":{...}} if it was cached — then you're done, skip polling).
   Poll every ~5s until status is done | refused | failed:
   JOB_ID="<from submit response>"
   curl "https://uniquenessengine.com/api/jobs/$JOB_ID" -H "authorization: Bearer $UNIQUENESS_API_KEY"
   When "status":"done", the brief is at .result. On cache-hit submit, the brief is at top-level .brief. Confirm it has "status":"ok" and a safe_to_reference array (each fact carries the quote it came from in evidence_quote and its source link in source_url). Broader interest signals and the personality read are clearly marked as a read, not a fact. Every fact also carries a "category" (e.g. "family_or_children", "health", "authored_work") so you know what KIND of fact it is; sensitive facts may carry "special_category":true (health/recovery/religion/politics/protected attributes) — still real and surfaced, never blocked. We verify and LABEL facts; we don't tell you what's safe to send — how you use a fact is your call, informed by the category. (The old "safe_to_use_in_outreach" stamp and the "outreach_angles"/"gift_hook" fields were removed — they're declared in the brief's "capabilities" block and never returned.)

   Response paths:
   - HTTP 200 + status:"done" + brief: cache hit; no poll; costs 1 credit unless this account already unlocked the person.
   - HTTP 202/job_id + status:"queued": poll GET /api/jobs/$JOB_ID every ~5s.
   - Poll status:"refused": identity gate failed; .result.status is needs_review; not charged.
   - HTTP 402 payment_required: paid admission did not have enough spendable credit. Show the offered pack terms and ask the human before opening Checkout; never purchase, save a method, enable auto-recharge, or replay the target by inference. See step 5.

3b) TEST a refusal while credits_remaining >= 1 (confirms the "we never invent it" behavior, and that it consumes no credit). With 0 credits, paid admission returns the canonical HTTP 402 before live work, so this check requires one available credit to reserve and release.
   curl -X POST https://uniquenessengine.com/api/enrich \
     -H "authorization: Bearer $UNIQUENESS_API_KEY" \
     -H 'content-type: application/json' \
     -d '{"name":"Zzqrx Nonexistentperson","company":"NotARealCompany9999"}'
   Poll the returned job_id. Confirm the job ends "status":"refused" (its .result has "status":"needs_review", usage.credits_charged 0). The exact reserved allocation is released. This is correct behavior, not an error — the engine refuses rather than guessing when it can't verify a real person.

4) CHOOSE how you'll call it going forward (pick what fits your environment — all three call the same API):
   - Direct API (works everywhere, no install): repeat the submit→poll from step 3. The deprecated /api/brief compatibility alias now follows the same async paid-admission contract; prefer /api/enrich for new integrations.
   - CLI: npm install -g uniqueness   (handles submit+poll for you)
     uniqueness example   (free synthetic sample brief — no key, no charge; confirms the CLI works)
     uniqueness brief --linkedin-url https://www.linkedin.com/in/ --json
     uniqueness feedback up|down --canonical-id    (rate a brief 👍/👎)
     uniqueness account
     uniqueness billing status|packs|subscriptions|portal
     uniqueness billing auto-recharge enable|disable|retry   (every change requires explicit human confirmation)
   - MCP server (seven conservative native tools: begin_programmatic_signup, complete_programmatic_signup, get_connection_brief, resume_connection_brief, get_billing_status, preflight_connection_briefs, submit_feedback):
     { "mcpServers": { "uniqueness": { "command": "npx", "args": ["-y", "uniqueness-mcp"], "env": { "UNIQUENESS_API_KEY": "uq_live_..." } } } }
     MCP stores no unpaid target. After human-approved Checkout, resume_connection_brief requires the host to resupply the original target, payment_required.retry.idempotency_key, and payment_required.credits.available; the API rejects a mismatched retry identity.
     Smoke test after adding config: call get_connection_brief with the user's own linkedin_url only when paid credit is available, and confirm it returns brief JSON. To inspect the shape first, GET the fictional static fixture at https://uniquenessengine.com/api/examples/kitchen-sink. Config-only is not verified.
     After a brief, you can call submit_feedback with rating="up"|"down" and the brief's identity.canonical_id to help the engine improve (never charges/refunds a credit).

4b) BATCH PREFLIGHT for lists. Estimate before submitting a batch so you know likely credit usage:
   curl -X POST https://uniquenessengine.com/api/enrich/batch \
     -H "authorization: Bearer $UNIQUENESS_API_KEY" \
     -H 'content-type: application/json' \
     -d '{"estimate_only":true,"profiles":[{"linkedin_url":"https://www.linkedin.com/in/"}]}'
   Read estimate.max_charge, estimate.likely_charge, estimate.balance, estimate.need_topup, and estimate.shortfall_if_all_resolve. likely_charge is advisory and may understate charges for globally cached people; use max_charge as the safe ceiling. Do not fire dozens of parallel POST /api/enrich calls; use the batch endpoint or sequential submit with balance checks.

5) BILLING — Jordan Ellis is the only free experience and is fictional static data. Every real enrichment requires one paid credit and always uses full-quality written enrichment. The repeatable 5-Pack is five permanent credits for a $5 USD subtotal plus applicable tax; larger permanent packs are 20/$7.40, 50/$18.50, and 100/$37. Existing subscriptions are unchanged. Auto-recharge is separate explicit consent, off by default; saving a payment method does not enable it.
   GET https://uniquenessengine.com/api/billing/catalog is the read-only source of truth for pack and subscription terms. It contains no account, target, credential, or purchase action.
   The only purchase actions come from a canonical HTTP 402 payment_required response: payment_required.recommended_offer.checkout_url opens the offered target-free pack, and payment_required.billing_url opens the target-free pack selector. First show the returned credits, tax-exclusive subtotal, applicable-tax notice, and expiry. Then [ASK USER] for explicit consent before opening either URL. Never use a payment-method setup route or treat a saved method as a purchase.
   After the human completes Checkout, do not assume payment succeeded. Confirm the service reports new spendable credit, then resubmit only with payment_required.retry.idempotency_key before its expiry. If it expires, submit a new request; never replay a target by inference.
   To cancel or update the card later: curl -X POST https://uniquenessengine.com/api/billing/portal → returns a Stripe-hosted management link.

6) DONE. Call POST /api/enrich (then poll GET /api/jobs/:id) with any linkedin_url (or name + company) from here on. An exact credit allocation is reserved on submit and released on refusal/wrong-person/no-result/failure. A successful first unlock costs 1 credit, including a global cache hit; a same-account re-pull costs 0 unless refresh:true. Check GET /api/account any time for balance and billing status.
   If a key ever leaks, revoke that named key in Account and create a replacement there. The new secret is shown once; existing keys are never re-disclosed.

Every endpoint above is real and live — this isn't aspirational copy, it's the actual API.

What you get back

{
  "status": "ok",
  "identity": { "full_name": "...", "title": "...", "company": "...", "status": "resolved" },
  "safe_to_reference": [
    { "claim": "...", "evidence_quote": "quote from the source", "source_url": "...",
      "connection_type": "personal_signal", "category": "family_or_children",
      "special_category": false, "band": "safe", "mentionability": 0.9 }
  ],
  "personality": { "archetype": "...", "disc_label": "...", "how_to_communicate": ["..."], "predicted": true },
  "capabilities": { "outreach_angles": "removed", "gift_hook": "disabled", "detail": "compact", "full_available": true },
  "usage": { "cache_status": "hit|miss", "credits_charged": 1, "credits_remaining": 9 }
}
# full by default in production; pass ?detail=compact for the smaller shape

Personal vs. professional signal is split via connection_type. Facts in safe_to_reference are click-to-verify through evidence_quote + source_url. They are separate from the broader interest signals in aggregated_interests, which are clearly marked as a read, not a fact (?detail=full only). New discovery denies FEC, court-record, obituary, wedding, and people-search URLs, strips addresses at ingestion, and drops pages that never name the target. category / special_category label what KIND of fact it is (sensitivity is a label, not a block — only home/physical addresses and private contact info are hard blocked). We verify and label; we don't tell you what's safe to send — the removed safe_to_use_in_outreach, outreach_angles, and gift_hook are declared in capabilities and never returned. Full contract: /openapi.json.

Honest limits, for the agent reading this

- A Checkout action can never be completed by an agent alone. Only after explicit human
  consent, surface the 402's recommended_offer.checkout_url or billing_url; Stripe requires a
  real human to finish on its hosted page. Do not claim a purchase succeeded until the service
  reports spendable credit.
- needs_review responses are not a bug -- the engine refuses rather than guesses when it
  can't confirm identity or confirm a fact in public text. Don't retry expecting a different answer; the
  signal genuinely isn't there.
- Rate limits exist per API key (burst + sustained) and per signup IP. A 429 means slow down,
  not "try a different key."
- Never put UNIQUENESS_API_KEY in client-side/browser code -- it's a server-side secret. If it
  ends up in a repo, log, or anywhere public, rotate it (step 6) immediately.
- Call /api/* directly, not the website's HTML pages -- those sit behind bot protection and can
  403 a bot-like User-Agent, while API routes don't. Sending a descriptive User-Agent naming your
  tool/agent is good citizenship and helps us debug, though it isn't required -- default library
  User-Agents aren't blocked on /api/*.