title: Job Collar (AI) — Complete Overview version: "1.0" status: draft owner: mshoaib last_updated: 2026-06-18 repo_path: docs/job-collar-overview.md related:
- workflow-diagram.md
- security-questionnaire.md supersedes: null
Job Collar (AI) — complete overview
Job Collar (AI) is an intelligence and opportunity-discovery assistant for recruiters, built on the JobAdder API with compliant external enrichment. It isn't a search box — it surfaces business opportunities, relationships, movers, trends and next actions a recruiter couldn't find manually, and it can take bulk actions. First customer (pilot): Talent Flow (the pilot agency), a ServiceNow recruitment specialist.
This single document covers: features → use cases → how it works (technical) → features & data sourcing → security → JobAdder partner process → commercials & pricing. (Setup/run instructions are deliberately excluded at this stage.)
1. Features
Each feature is tagged Data (runs on the agency's own JobAdder data + AI — instant, high margin) or Enrichment (needs a licensed data provider — premium).
- Job-to-candidate matching (Data) — paste a JD; get a ranked shortlist with a reason per candidate, understanding meaning ("ServiceNow ITSM" ≈ "ServiceNow admin").
- BD opportunity finder (Data, +Enrichment) — e.g. companies that hired several of your candidates but have no live roles with you → warm target list + a drafted opener.
- Relationship & connection mapping (Data) — "who worked at [target client] or with this contact?" → warm-intro paths and insiders.
- Job-change (mover) detection (Enrichment) — refresh placed candidates' current role → "12 people you placed ~2 years ago just moved" → re-engage + a BD signal.
- Placement trend analytics (Data) — time-to-fill, source conversion, pipeline drop-off, seasonal demand — in plain English.
- Next-action recommendations (Data) — reads a candidate's background, suggests the approach and drafts the message.
- Auto note-logging (Data) — writes call/email summaries straight into JobAdder — the biggest admin drain.
- JD & candidate write-ups (Data) — brief → job description; profile → client-ready summary.
- Duplicate & data-hygiene sweep (Data) — flags duplicates and incomplete records, proposes merges/fixes.
- Bulk actions (Data, +email) — bulk field updates (fill-empty, audited, reversible) or a personalised email per person, sent on approval.
Tiers: Tier 1 (FAQ/chat) and Tier 2 (search + actions) are the path; Tier 3 — intelligence & opportunity discovery (features 1–9 + enrichment) is the real product and marketplace differentiator.
2. Use cases (a recruiter's day)
What they do manually today vs with Job Collar:
- New role lands: today, boolean + open 40 profiles (1–2 hrs). Now: paste the JD → top 10 ranked with reasons in seconds.
- Need new business: today, scroll placements and guess. Now: a ranked BD call list.
- Who's moved: today, found out by accident. Now: a weekly "movers" digest.
- End-of-day admin: ~13 hrs/week lost to notes/updates/follow-ups. Now: drafted for approval.
- Chasing a shortlist: today, copy-paste 50 emails. Now: one instruction → personalised emails → approve & send.
- Messy CRM: duplicates skew searches. Now: flagged with proposed fixes.
- Desk review: today, export + pivot. Now: instant stats + a short read-out.
Other manual tasks it removes (from industry research): updating ATS records & logging notes (85% of recruiters already use AI for this), writing JDs & candidate write-ups, sending repetitive status emails, resume pre-screening, de-duplicating the CRM, and reporting.
Context: recruiters lose 10–20 hrs/week to repetitive tasks; ~35% of time goes to scheduling/screening. Job Collar gives those hours back and surfaces opportunities they'd never find by hand.
Suggested pilot for the first agency (prove Tier 3 fast)
- BD-opportunity finder (pure JA data — the "wow", zero external cost)
- Next-action + drafted outreach (visible daily value)
- Job-change spotter (the compliant "beyond JobAdder" feature)
3. How it works (technical workflow)
Integration flow
Recruiter ──1. connect once (OAuth 2.0, scoped)──▶ JobAdder login + approve
│ ◀── access + refresh tokens
│ 2. ask / task (chat or scheduled)
▼
┌──────────────────────────────────────────────┐
│ OUR BACKEND (Python, server-side only) │
│ auth + encrypted tokens · audit trail │
│ ┌────────────────────────────────────────┐ │
│ │ Intelligence layer (Claude reasoning) │ │
│ └──────┬─────────────────────────┬────────┘ │
└──────────┼ 3a. read/write (scoped) ┼ 3b. licensed enrichment ─┐
▼ ▼ │
┌──────────────────┐ ┌──────────────────────┐ │
│ JobAdder API v2 │ │ Licensed provider │ │
│ candidates / │ │ (e.g. Datablist) │ │
│ contacts / │ │ — NOT scraping │ │
│ placements │ └──────────────────────┘ │
└──────────────────┘ │
└── 4. reasoned answer / action / pushed opportunity ─┘ → recruiter
Rules: all API + enrichment calls are server-side; tokens encrypted; every write is audited and reversible; external data is licensed. (Visual architecture + OAuth sequence diagrams are in workflow-diagram.md.)
Components
| Component | Responsibility |
|---|---|
| Auth & token service | OAuth 2.0; encrypted token store; auto-refresh; CSRF state |
| AI orchestration (Claude) | reasoning + deciding which tools to call |
| JobAdder tools | search / update / analyse via the API |
| Reliability & safety | 429/Retry-After handling; audit trail of writes |
| Tenant store | per-agency data isolation (Postgres + vector index at scale) |
Design choices: config-driven multi-tenant (change behaviour without redeploy); tools for real actions; platform-agnostic embed (sites load a widget, the brain stays on our backend); the AI model is a config setting and can be swapped/upgraded anytime.
Scaling to a real product
| Stage | Build | Why |
|---|---|---|
| 0 — Pilot (first agency) | deploy to cloud (HTTPS), real OAuth + paid key, 2–3 features | prove value, start charging |
| 1 — Multi-tenant | per-agency isolation of tokens/data/settings | sell to many agencies |
| 2 — Own data layer ⭐ | periodically sync each agency's data into our DB | fast aggregation, avoid rate limits |
| 3 — Semantic search | vector embeddings (pgvector); Claude re-ranks top N | JD matching scales to 10k+ profiles |
| 4 — Background jobs | scheduler + workers (sync, enrichment, metrics); budgets/caching | cost & rate-limit control |
| 5 — Hardening | usage metering, secret manager, encrypted tokens, logging, admin UI | real SaaS |
Design targets: 5k–50k+ candidates per agency (pilot agency ~4.8k); adding the 50th agency is config, not a rebuild.
4. Features & data sourcing (under the hood)
Every feature follows: pull data → reason over it → return an outcome/action.
| Feature | Pulls from | Reasoning / action | Source |
|---|---|---|---|
| Job-to-candidate matching | GET /candidates (resume, skills, history) | meaning-based fit score + reason | Data |
| BD opportunity finder | GET /placements, /companies, /contacts | hires vs live roles & contact recency | Data (+Enrich) |
| Relationship mapping | candidate employment history + contacts | who-worked-where overlaps | Data |
| Mover detection | placed candidates + LinkedIn URL | licensed lookup of current role, compared | Enrichment |
| Trend analytics | placements, jobs, applications (dates/stages) | compute metrics, then explain | Data |
| Bulk update / email | a selected group | PUT updates (audited) or drafted emails | Data |
| Auto note-logging | a call/email summary input | writes a clean note back | Data |
| JD / write-ups | a brief or candidate profile | generates JD / client-ready summary | Data |
| Next action | one record | suggests + drafts the next step | Data |
Where the data comes from (the compliance line)
- The agency's own JobAdder data does most of the work — matching, relationships, trends, prioritisation, next actions, write-ups. No external source, no extra cost.
- "Live external data" (e.g. a candidate's current role) comes from a licensed enrichment provider (e.g. Datablist) or candidate consent.
- We do NOT scrape LinkedIn (or any site). Scraping breaks LinkedIn's terms, risks bans/legal exposure, and fails JobAdder's partner security review (scrapers like Proxycurl were shut down). The licensed route gives the same outcome, compliantly.
Intelligence from JobAdder data alone vs enrichment
- JobAdder data alone (instant, high margin): matching, BD targets, relationships, trends, prioritisation, next actions, write-ups, hygiene — most of the intelligence; a strong base subscription.
- Licensed enrichment (premium, metered): mover detection, fresh contacts, net-new candidates — pass cost + margin → recurring upside.
Honest limits
No live LinkedIn scraping; output quality depends on data completeness; API rate limits mean mass tasks run reliably but take time (proven on ~4,800 records in Phase 2); scheduling needs a calendar integration and bulk send needs an email integration.
5. Security
Job Collar is a server-side integration; the browser never calls the JobAdder API or holds tokens. Posture against JobAdder's security questionnaire:
| # | Topic | Position |
|---|---|---|
| 1 | Token security 🚫 | server-side, encrypted at rest |
| 2 | Credential collection 🚫 | OAuth 2.0 only — no passwords/personal tokens collected |
| 3 | Transport security 🚫 | TLS 1.2+ on all API calls |
| 4 | State validation 🚫 | cryptographically random state, verified, single-use |
| 5 | Dependency scanning 🚫 | automated SCA (Dependabot + pip-audit) |
| 6 | Secrets management 🚫 | env vars / secret manager; nothing in source |
| 7 | Input validation ⚠️ | FastAPI + Pydantic on all inputs |
| 8 | CSRF ⚠️ | verified OAuth state + CORS allow-list; writes server-side |
| 9 | Scope limitation ⚠️ | least privilege (list below) |
| 10 | Data at rest ⚠️ | managed DB AES-256, per-tenant, minimal retention |
| 11 | Vulnerability scanning ℹ️ | SCA + SAST (bandit) in CI |
| 12 | Data egress ℹ️ | text to AI provider (Claude) + minimal fields to licensed enrichment, both over TLS; no bulk export, no scraping |
Full answer text for the form is in security-questionnaire.md.
Scopes (least privilege): read_candidate, write_candidate, read_contact,
write_contact, read_placement, offline_access.
6. JobAdder partner process
JobAdder Partnerships start by asking for a high-level workflow diagram + completed Security Questionnaire. Full path:
- Submit workflow diagram + Security Questionnaire → request API access.
- Their team reviews workflow, use cases, security.
- Developer account + sandbox set up.
- We submit a detailed workflow (all endpoints + webhooks).
- Technical review.
- We build against
https://api.jobadder.com/v2/docs. - We submit an integration test form; they verify.
- Marketplace listing (their marketing team).
Endpoints (detailed-workflow stage)
| Purpose | Method · Endpoint |
|---|---|
| OAuth authorize / token | id.jobadder.com/connect/authorize, /connect/token |
| Candidates | GET /v2/candidates, GET/PUT /v2/candidates/{id} |
| Contacts | GET /v2/contacts, GET/PUT /v2/contacts/{id} |
| Companies | GET /v2/companies/{id} |
| Placements (analytics) | GET /v2/placements |
Webhooks
| Aspect | Approach |
|---|---|
| Registration | subscribe via the API to our HTTPS callback (set up in the sandbox) |
| Required scope | offline_access (+ the resource's read scope) |
| Events | candidate created/updated, status changed, contact created/updated, placement created/updated (exact names confirmed in the live docs/sandbox) |
| Delivery | JobAdder POSTs JSON to our callback over HTTPS; we verify + process via a worker |
| MVP stance | start without webhooks (scheduled sync is enough); add at the data-sync stage |
7. Commercials & pricing
How selling on the marketplace works (researched, 2026)
JobAdder gives partners a developer account, scoped API access and a marketplace listing for exposure + co-marketing. It does not publish partner fees or revenue-share, and existing partners (Jobma, Referoo, Shazamme…) each have their own pricing and sell direct. So the model: we build + list; the partner sells directly and sets the price. Evidence points to no JobAdder cut on direct sales — confirm at onboarding (a listing fee or a cut on JobAdder-introduced leads can't be ruled out without asking).
Billing — who pays whom
- Agency → partner/reseller: one monthly price the partner sets.
- Partner/reseller → us: one-off build fee + per-client fee + monthly maintenance.
- Running costs (out of the price): Claude (~cents/chat), enrichment (per record), hosting (~fixed monthly).
Agency pays partner $300 / month (illustrative — partner sets it)
├─ Partner pays us $X / month per client (+ build fee)
├─ Claude API ~$10–40 / month (usage-based)
├─ Enrichment ~per record (only when used)
├─ Hosting ~$10–30 / month
└─ JobAdder cut $0 expected on direct sales (confirm)
→ the rest is the partner's margin
Pricing by tier (illustrative guides — partner sets final)
| Tier | What they get | Setup (one-off) | Monthly |
|---|---|---|---|
| 1 — Assistant / FAQ chat | branded chat, answers from their content, lead capture | $500 – $1,000 | $99 – $199 |
| 2 — Search + actions | candidate search, bulk update, bulk email | $1,500 – $2,500 | $299 – $499 |
| 3 — Intelligence | BD leads, movers, trends, relationships, next actions, write-ups | $3,000 – $6,000 | $599 – $1,200 |
Enrichment is a metered add-on (provider cost + margin), charged only when used. For the pilot agency: a discounted Tier-3 build to prove value, then standard pricing for later agencies.
Model selection (flexible — not locked in)
The AI model is a per-tenant config setting and can change anytime without a rebuild.
| Model | Input/Output per 1M | Best for |
|---|---|---|
| Claude Opus 4.8 (default) | $5 / $25 | hardest reasoning — BD insight, trends, matching |
| Claude Sonnet 4.6 | $3 / $15 | balanced — most chat + search at lower cost |
| Claude Haiku 4.5 | $1 / $5 | cheap/fast — simple FAQ, high volume |
Start on Opus for quality during the pilot, then tune per tenant/feature to balance cost and quality.
Deployment posture: cloud or local AI structure
The same orchestration layer is deployment-agnostic and can be pointed at either a managed AI service or a local/self-hosted AI structure:
- Managed AI services — fastest setup, no infrastructure overhead.
- Local / private AI inference — run open-weight models on your own GPU or CPU infrastructure (e.g., Ollama, vLLM, llama.cpp) or any OpenAI-compatible local endpoint for full data sovereignty and air-gapped environments.
- Hybrid mode — keep sensitive reasoning on a local AI structure while using cloud models for lower-sensitivity tasks.
Provider selection, model selection, and endpoint configuration are all tenant-level settings. Switching between a cloud AI provider and a local AI structure is a configuration change — no application rebuild is required.
Questions to confirm with JobAdder Partnerships
- Any listing/certification fees for a tech integration?
- Any revenue share — all sales, or only JobAdder-introduced leads?
- Do partners bill customers directly?
- Any minimum pricing / packaging rules?
- Co-marketing support once listed?