Saves a job posting found anywhere on the open web into the user's tracker. For jobs that came
from jobs_search results, tracker_add (which takes a job_id) is the right tool instead. A job
seen elsewhere in the conversation needs no prior jobs_search call — its URL and details from
the conversation are sufficient input.
`url`, `company_name`, `title_name`, `location_name`, and `description` identify the posting
and are the only required fields. Every structured fact field (salary, dates, employment type,
education, experience) is optional: a fact the source does not state is simply omitted (or
null), and FoundRole's own extractors derive missing salary, employment, work-arrangement,
education, experience, skills, benefits, and bonuses from the description. A save never waits
on facts the source did not provide. The optional `client_extraction` object carries
evidence-backed skills, technology, benefits, bonuses, seniority, industry, management,
clearance, visa, and remote-scope labels when source excerpts for them exist; FoundRole
validates and stores those labels separately.
Fields:
- `url`: the job posting's direct URL (required; not a company homepage)
- `company_name`: company name (required)
- `title_name`: job title (required)
- `location_name`: location, e.g. "New York, NY" (required)
- `description`: the posting's description from the source result; a short summary is acceptable (required)
- `salary_min_value` / `salary_max_value`: salary range bounds (numbers)
- `salary_value`: a single salary figure when there is no range (number)
- `posted_at`: ISO 8601 posting date
- `salary_currency`: ISO 4217 currency code
- `salary_type`: one of year, month, week, day, hour
- `employment_type`: array of full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other
- `work_location_type`: one of on_site, remote, hybrid
- `education_requirements`: array of no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree
- `experience_months`: minimum required experience in months (number)
- `client_extraction`: evidence-backed extraction object; fields without source evidence are omitted
- `status`: initial tracking status (saved, applied, interviewing, offered, archived); defaults to "saved"
- `sub_status`: sub-status within the main status: saved: interested, researching_company, preparing_application, ready_to_apply; applied: application_submitted, followed_up; interviewing: interview_scheduled, phone_screen, technical, onsite, final_round, pending_feedback; offered: negotiating, considering, offer_received, accepted; archived: ghosted, rejected_by_company, withdrawn_by_candidate, not_interested, employed_by_this_company, employed_by_another_company
- `notes`: notes about the job
Returns the tracked job. Repeated saves return the existing tracked job.