# Uniqueness Engine

Commercial contract: `hard-paid-v1`.

> LinkedIn URL in. Personal facts out. Uniqueness Engine is the trust layer before every meeting:
> give a LinkedIn URL (or name + company), get a fact-checked Connection Brief centered on PERSONAL
> signal -- hobbies, the team they root for, causes, pets, and tastes -- mapped onto their
> professional presence (which is just the anchor, not the payload; anyone can pull a job
> title). Plus broader interest signals and a personality read for how to reach them. 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. The product refuses rather than guesses when it
> can't confirm identity or confirm a fact in real text.

Profiles and public social posts 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 before any paid source. Every candidate still passes the same
identity and fact checks.

## Setup for agents

- [/agents](https://uniquenessengine.com/agents): copy-paste prompt that walks an AI coding
  agent through signup, the free example fixture (GET /api/examples/kitchen-sink), a user's own
  test call, batch estimate preflight, MCP smoke test, and human-approved 402 billing recovery.
- [/documentation](https://uniquenessengine.com/documentation): full endpoint reference
  (auth, every endpoint, billing/credit rules, rate limits, errors).
- [/documentation/mcp/quickstart](https://uniquenessengine.com/documentation/mcp/quickstart):
  MCP config block + example tool call/response shapes.
- [/agent-manifest.json](https://uniquenessengine.com/agent-manifest.json): structured JSON
  --  endpoint registry, routing table (task -> endpoint), MCP config.

## API

- Base URL: https://uniquenessengine.com
- `POST /api/signup` `{email,client_name,device_name}` -> opaque email-verification
  transaction. Approval creates a newly revocable API key named for `client_name`
  exactly once; it never grants a free live credit. On
  `503 verification_delivery_failed`, no usable polling secret or key was issued:
  honor `Retry-After` and begin a fresh transaction.
- `POST /api/enrich` `{linkedin_url}` (or `name`+`company`) -> Bearer auth -> PRIMARY path. A
  brief usually takes 45-90s (up to ~2-3 min), so this returns `202 {job_id, status:"queued"}` (or `200 {status:"done",
  brief}` on a cache hit). An exact credit allocation is reserved on submit and released if the brief refuses
  or fails.
- `GET /api/jobs/:id` -> Bearer auth -> poll the job every ~5s. While running it returns a coarse
  `stage` (resolving_identity -> collecting_sources -> extracting_evidence -> verifying ->
  generating). Terminal: `done` (brief in `result`), `refused` (needs_review, no charge), `failed`
  (no charge).
- OPTIONAL `sender` on `/api/enrich` + `/api/brief`: `{sender:{name,company,role,offer,shared:["University of Maryland"]}}`
  — optional context about you, the sender. `shared` is your own assertion of facts you genuinely
  have in common; the engine never invents a shared background. The API returns verified facts +
  labels only — it does NOT write openers or outreach angles (decommissioned; declared in
  `capabilities`); how you use a fact is your call. Full param reference: `/openapi.json`.
- `POST /api/brief` `{linkedin_url}` (or `name`+`company`) -> Bearer auth -> DEPRECATED
  compatibility alias. It follows the same paid async contract: cache hits return inline;
  uncached work returns a `job_id` to poll. Prefer `/api/enrich` for new integrations.
- Response shape defaults to FULL in production. Pass `?detail=compact` explicitly for identity,
  top-ranked `safe_to_reference`, one `personality.how_to_communicate`, compliance labels, and a
  `capabilities` block; pass `?detail=full` explicitly for all fact arrays, sub-scores, and
  `evidence[]`. An invalid `detail` value returns
  `400 invalid_detail`. Async `/api/enrich` responses include a `poll_url` carrying your detail.
  The removed fields `outreach_angles` / `gift_hook` / `safe_to_use_in_outreach` are declared in
  `capabilities` and never returned.
- `GET /openapi.json` -> machine-readable OpenAPI 3.1 contract. Brief-body schemas and examples
  are derived from the response serializer; endpoint envelopes, errors, and descriptive text are
  maintained separately.
- `GET /api/examples/kitchen-sink` -> free, no-key synthetic sample brief ("Jordan Ellis",
  `mode:"synthetic_fixture"`, `not_a_real_person:true`, `billing.charged:false`); defaults to full,
  `?detail=compact` for the compact shape.
- `GET /api/account` -> Bearer auth -> credits remaining + billing status.
- `GET /api/billing/catalog` -> no auth -> canonical read-only pack and
  subscription terms plus the Account destination; no Checkout action or
  purchase.
- `POST /api/account/rotate-key` -> Bearer auth (old key) -> revokes it immediately, returns a
  fresh key once. If the key is lost, sign in by email at `/account` and rotate all account keys;
  `/app` is the main passwordless dashboard.
- `POST /api/billing/checkout` -> a verified-account credit-pack Checkout. Do not
  autonomously open/purchase it for a user; it is account-bound and target-free on
  API/MCP paths.
- `POST /api/feedback` `{rating:"up"|"down", canonical_id (or job_id), note?}` -> Bearer auth -> rate a brief 👍/👎 so the engine improves. Never charges or refunds a credit.
- `GET /api/health` -> service status.
- Billing: one paid credit runs the full-quality written enrichment. Refusal,
  wrong-person, no-result, and failed outcomes cost 0. Return credit is a
  self-service credit remedy for a delivered poor brief; cash refunds are support
  controlled.

## Access surfaces

- Direct API (curl/fetch), no install. Hit `/api/*`, not the website's HTML pages -- those are
  bot-protected and may 403 a bot-like User-Agent. Sending a descriptive `User-Agent` naming your
  tool/agent is good citizenship and helps with debugging, though it isn't required -- default
  library User-Agents aren't blocked on `/api/*`.
- CLI: `npm install -g uniqueness` (https://www.npmjs.com/package/uniqueness).
  Use `uniqueness billing packs` to review permanent packs in an account-bound
  chooser, `uniqueness billing subscriptions` to compare the unchanged monthly
  plans, and `uniqueness billing auto-recharge enable|disable|retry` only with
  explicit human authorization. Non-interactive/JSON commands never open a
  browser or start a purchase.
- MCP server: `npx -y uniqueness-mcp` (https://www.npmjs.com/package/uniqueness-mcp) --
  gives any MCP-compatible agent `get_connection_brief` + `submit_feedback` tools.

## Pricing

Jordan Ellis is a fictional static fixture and the only free product experience;
it never runs live enrichment. Real enrichments require paid credit. The repeatable
5-Pack is five permanent full-quality written credits for a $5 USD tax-exclusive
subtotal plus applicable tax; permanent packs are also 20/$7.40, 50/$18.50, and
100/$37. Existing Starter ($15/45), Growth ($40/130), and Pro ($90/300)
subscriptions are unchanged. Purchased credits never expire; subscription grants
roll for two months and forfeit on cancellation. Auto-recharge is a separately
consented 20/$7.40 option, off by default; saving a payment method never enables it.

## Machine-readable summaries

- [AI policy](https://uniquenessengine.com/.well-known/ai.txt): crawler policy and pointers
- [Site summary](https://uniquenessengine.com/ai/summary.json): compact JSON for agents
- [FAQ](https://uniquenessengine.com/ai/faq.json): common questions
- [Service](https://uniquenessengine.com/ai/service.json): product description for tools
- [Sitemap](https://uniquenessengine.com/sitemap.xml): crawlable page list

## Trust boundaries

- 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.
- New discovery hard-denies FEC, court-record, obituary, wedding, and people-search URLs,
  strips addresses at ingestion, and drops fetched pages that never name the target.
- Facts in `safe_to_reference[]` carry `category` (e.g. `family_or_children`, `health`,
  `authored_work`) and `special_category` (GDPR Art.9: health/religion/politics/protected
  attribute/sexual orientation) -- sensitivity is a LABEL, not a block. Only home/physical
  addresses (`home_location`) and private contact info (`private_contact`) are hard-blocked
  and never surfaced. We verify and LABEL facts; we do not tell you what is safe to send --
  how you use a fact is your call, informed by `category` / `special_category`.
- `negative_preferences` remains in the full response schema but is currently disabled and
  normally returns `[]`.
- No fabricated reviews, ratings, or social profiles in structured data.
- Contact: support@uniquenessengine.com
- Last updated: 2026-07-22