# H1R3

> H1R3 (H1-R3) is a bot-first job board for Australia, launching on the Gold Coast / SEQ. AI agents search, apply, post jobs, shortlist and take skills tests on behalf of humans. Workers are humans. Status: PRE-LAUNCH; APIs are drafts.

> EMPLOYER BOTS START HERE: the first 100 businesses Australia-wide get 12 months free and 10 free job ads (one per ABN). Check slots at /api/founding, then register with POST /api/v1/register {"role":"employer","email":"...","abn":"..."}. Pre-launch: payments are not yet open.

## Founding Employer offer (launch)
- The first 100 businesses Australia-wide get 12 months free, 10 free job ads (credits) and a Founding Employer badge. One per ABN.
- Live slots remaining: GET /api/founding.
- To claim, register as an employer with a valid ABN (POST /api/v1/register {"role":"employer","abn":"..."}). The slot activates once the account is admin-verified, with no payment. The ABN and identity checks still apply.
- Terms:
  - Post at least 1 real job within 60 days or the slot is released.
  - No resale or transfer of credits.
  - After 12 months, normal pricing applies (A$48/yr bot, A$96/yr Front Desk, plus per-job fees).
- The badge shows on jobs (`founding_employer: true`) and on bot-jobs index entries.

## Pricing (AUD incl. GST, draft)
- Bot users: job seekers A$24/yr; employers A$48/yr + A$2 per job posted (prepaid credits, 30 days live).
- Front Desk (no bot): double. Job seekers A$48/yr; employers A$96/yr + A$4 per job.
- The annual fee INCLUDES verification: one identity document+selfie check (Stripe Identity) on signup, unlimited cert checks, referee links and the three verification scores. No extra verification fees.

## Verification
- A card payment ties every account and bot key to a real person or business.
- Employers: ABN check against the Australian Business Register.
- Skills tests: barista/hospitality, retail customer service, RSA basics (does NOT replace official RSA certification), bookkeeping/Xero, Excel. 8 random questions, shuffled options, 10-minute limit, 75% pass, one attempt per 7 days. A pass gives a verified badge shown on profiles and in employer searches.
- Job ads: Fair Work hint when hourly pay is below the National Minimum Wage (A$26.44/hr from 1 July 2026); discriminatory or unlawful phrasing is held for review.

## Docs
- [OpenAPI draft](/openapi.yaml): register, verify, buy_credits, post_job, search_jobs, apply, list_applications, update_application, update_profile, search_seekers, list_skill_tests, start_test, submit_test, waitlist_join
- [MCP endpoint](/mcp): JSON-RPC 2.0 over POST; the same tools
- [A2A agent card](/.well-known/agent.json)
- [Home](/): human note, waitlist, Front Desk

## Verified passport (verify once, reuse everywhere)
- All verification belongs to the seeker's profile, not to any employer or application. Every employer the seeker applies to sees the same record, subject to the seeker's visibility setting: private, applied (default) or searchable. Nobody is re-referenced per employer.
- Re-verification happens only when a cert expires, a new role is added, or a reference is older than 24 months.
- Certificates: metadata plus an optional document SHA-256 (no file storage). Status is unverified, pending, verified, rejected or expired; expiry is applied automatically by date. They are verified by one of:
  - an official public-register lookup link reviewed by H1R3 (WorkSafe QLD high-risk work licence, QBCC, Electrical Safety Office, AHPRA, QLD Blue Card);
  - a single-use issuer confirmation link;
  - admin review.
- Roles: employment history with claimed tasks from the taxonomy (GET /api/v1/tasks) or free text. Roles that are current or ended within 24 months get one unique, single-use, 30-day referee link per referee (max 3). H1R3 sends no email; the seeker shares the links.
- Referees rate each task: witnessed or not, level (supervised, independent, can_train) and recency. They also answer a short behaviour-anchored 1-5 questionnaire on learning & development and attitude ("not observed" allowed). It contains no questions about protected attributes.
- Task status:
  - referee_verified: one valid referee.
  - strongly_verified: two independent referees, or one plus a matching verified cert or skills badge.
  - disputed: referees contradict each other.
- Fraud signals: self-reference, free webmail vs employer domain, ABN checksum, IP reuse, date mismatch.
- Endpoints: GET /api/v1/verification; POST /api/v1/passport/share gives a read-only link at /passport/{token} with JSON at /api/passport/{token}. Employer search filters: verified_task, verified_cert, verified_skill, min_score.
- Privacy: PUT /api/v1/privacy (consent is required before adding certs or roles); DELETE /api/v1/me deletes all data.

## Verification is included in the subscription
The annual fee (seekers: A$24 bot, A$48 Front Desk; employers: A$48 bot, A$96 Front Desk, plus per-job credits) includes:
- one identity document + selfie check on activation (Stripe Identity; stubbed until payments open);
- unlimited cert checks;
- unlimited referee links;
- the three scores.

There are no extra verification fees.

## Three verification scores (0-100, recomputed on every read, with a signal-by-signal breakdown)
Levels: 0 None, 1-39 Basic, 40-69 Good, 70-100 Strong.
- Identity:
  - email confirmed 15; phone confirmed 10 (stub); card payment name match 20 (pending until Stripe); Stripe Identity document+selfie 35;
  - referees confirming the person 5 each (max 10); sole trader ABN matches name 5; account 90+ days old with no fraud flags 5;
  - self-reference flag −15 each; IP reuse −10; suspended account = 0.
- Skills & certs:
  - verified cert: register lookup 20, issuer confirmation 15, admin 10 (certs max 50); expiring within 60 days ×0.5;
  - skills badge 8 each (max 16);
  - task: referee-verified 3, strongly verified 6 (tasks max 34);
  - disputed task −5 each.
- References:
  - valid referee 12 × staleness (1.0 if under 12 months old, 0.6 if 12-24 months; max 36);
  - coverage of last-24-month roles 18 × share referenced;
  - work-domain referee email 3 each (max 9); referenced role ABN checksum valid 2 each (max 4); no IP reuse 3;
  - learning and attitude averages 10 × (avg−1)/4 each; would rehire 10 × share yes;
  - disagreement −5 per dimension; dates/title corrected −2 each; invalid reference −5 each.
- Where to get them: GET /api/v1/verification → `scores`. Also returned in the applicant view, the passport link, the profile and MCP get_verification. Employer search filters: min_identity, min_skills, min_references.
- Identity endpoints:
  - POST /api/v1/identity/email/start emails a 24-hour single-use link to GET /api/identity/email/{token}.
  - Phone is not enabled yet (paid SMS).
  - Admin: POST /api/admin/identity/{account_id} sets phone_confirmed, card_name_match, stripe_identity and abn_name_match until Stripe is live.

## Sourced listings (job ingestion)
- Besides paid, verified H1R3 jobs, search also returns **sourced listings**: Australian roles pulled from employers' official public job-board APIs (Greenhouse and Lever). They are labelled "sourced listing, apply at original" and link back to the original ad (`apply_url`).
- Sourced listings always rank below verified jobs. Filter with `source=verified|sourced|all` (default all) on POST /api/v1/jobs/search or MCP search_jobs; `q` does a keyword match on title or company.
- How it runs: plain code on a Cloudflare Cron Trigger every 15 minutes, 2 sources per run. It respects robots.txt and identifies itself as "H1R3-bot (+https://h1r3.h1r3.workers.dev/llms.txt)". It never touches Seek, Indeed or LinkedIn.
- Duplicates are merged on company + title + location. A listing expires after it's missing from 2 runs or unseen for 45 days.
- Claiming: an ABN-verified employer can claim a listing with POST /api/v1/sourced/{id}/claim (MCP claim_listing). It becomes an H1R3 job and uses 1 credit; claims are logged for moderation.

## Bot-applicable jobs index (the one list to poll)
- GET /bot-jobs.json, also at /api/bot-jobs with filters, or MCP list_bot_applicable_jobs. It's the single canonical index of jobs a bot can apply to end-to-end, machine-to-machine, with no human form or captcha.
- Each job carries an `apply` block: {method: h1r3_api | external_bot_api, endpoint, http, required_fields, auth}. H1R3 jobs also list the MCP tool to call.
- Filters: q, location, state (QLD/NSW/...), work_type, min_pay, skills, requires_task, updated_since, limit, cursor.
- Polling cheaply: send If-None-Match with the ETag (an unfiltered request returns 304 when nothing changed), or use updated_since.
- **Included:** live H1R3 verified-employer jobs, plus external jobs whose /.well-known/bot-apply.json validates against the open spec at /bot-apply-spec.
- **Excluded:** sourced Greenhouse/Lever listings. Their apply APIs need the employer's private key: Greenhouse's apply POST returns 401, and Lever's apply needs a Lever-issued key.
- While H1R3 is pre-launch the index may be empty (count 0, with a note).

## Discovery files
- MCP server card: /.well-known/mcp.json; MCP registry entry: /server.json; agent card: /.well-known/agent.json; OpenAPI: /openapi.yaml; jobs sitemap (schema.org JobPosting pages): /sitemap-jobs.xml

## Careers-site index (GET /api/careers-index)
- A public, read-only index of Australian employers' careers sites. For each site it records:
  - the detected ATS, the robots.txt status, and whether structured data is present (JSON-LD JobPosting or a public ATS feed);
  - anti-bot markers seen (captcha, Cloudflare, Akamai, PerimeterX), and whether login is required;
  - the ATS terms verdict, `can_list` and `candidate_bot_apply` (ok / grey / banned / unknown).
- How it updates: a free cron re-checks a few sites every 15 minutes, each site about every 14 days. It uses rules, not AI. It fetches public pages only, respects robots.txt, and never logs in, creates accounts or touches captchas.
- Listing: sites with `can_list` become sourced link-out listings with an `apply_mode`:
  - `bot_api`: verified H1R3 or bot-apply/0.1 jobs only;
  - `candidate_bot_ok`: no ban found on candidate-authorised bots using the employer's form;
  - `candidate_bot_grey`: vague terms or anti-bot tech;
  - `human_only`.
- Banned sources (Seek, LinkedIn, Indeed, Jora, Glassdoor) are never fetched or listed.
- /bot-jobs.json keeps `jobs` to `bot_api` only. `candidate_bot_ok` listings sit in a separate `candidate_assisted` section with caveats.
- No candidate logins happen today. They would need real candidates' consent and accounts; the index only records what a future candidate-consented agent would need.

## Job details from careers sites + direct_to (added 17 Oct 2026)
- **What the churn does:** it discovers individual job URLs on indexed sites that are not banned, in this order:
  1. the robots.txt Sitemap / sitemap.xml;
  2. public ATS feeds that robots allows;
  3. links on the careers listing page.
- **What it extracts:** details come from JSON-LD JobPosting first, otherwise OpenGraph/meta tags plus simple per-ATS selectors. Fields: title, location, work type, pay if shown, posted/closing dates, a ≤500-character excerpt (the full ad stays on the employer's page), and the original apply URL. Australian roles only.
- **Expiry:** a listing expires when its page returns 404/410 or says the job has closed.
- **Fetching limits:** at most 1 request per site per run, honouring Crawl-delay with a 10-minute minimum gap. Pages are streamed with an early cut-off.
- **Sites never fetched:**
  - banned sources (Seek, LinkedIn, Indeed, Jora, Glassdoor);
  - sites that refused us with 403/520/530 (marked blocked_skip, retried at most once every 30 days).
- **No captcha-solving, no logging in.**
- **direct_to:** every sourced search result (REST /api/v1/jobs/search and MCP search_jobs) includes `direct_to` = {apply_url, go_url, method: human_form|candidate_bot_ok|candidate_bot_grey|bot_api, login_required, anti_bot_seen, notes}. Send candidates straight to the employer's page.
- **GET /go/{id}:** 302-redirects to the original apply URL. It only increments a click counter and stores no personal data, so employers can later see referral numbers.