Save a job from another site to the tracker
tracker_add_externalSaves 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 datesalary_currency: ISO 4217 currency codesalary_type: one of year, month, week, day, houremployment_type: array of full_time, part_time, contractor, temporary, intern, volunteer, per_diem, otherwork_location_type: one of on_site, remote, hybrideducation_requirements: array of no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degreeexperience_months: minimum required experience in months (number)client_extraction: evidence-backed extraction object; fields without source evidence are omittedstatus: 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_companynotes: notes about the job
Returns the tracked job. Repeated saves return the existing tracked job.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Direct URL of the specific job posting; a company homepage is invalid | |
| notes | No | Notes about this job | |
| status | No | Initial tracking status: saved, applied, interviewing, offered, archived | |
| posted_at | No | Posting date as ISO 8601, when the source states it | |
| sub_status | No | Sub-status within the main status, valid only for that 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 | |
| title_name | Yes | Job title from the posting | |
| description | Yes | Complete posting text available in the conversation; a source summary is valid only when no fuller posting text is available | |
| salary_type | No | Salary period: year, month, week, day, hour | |
| company_name | Yes | Company name from the posting | |
| salary_value | No | Single salary amount, when the posting gives one figure instead of a range | |
| location_name | Yes | Location text from the posting, including Remote when stated | |
| employment_type | No | Employment types: full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other | |
| salary_currency | No | ISO 4217 salary currency code, when stated | |
| salary_max_value | No | Salary range maximum, when stated | |
| salary_min_value | No | Salary range minimum, when stated | |
| client_extraction | No | Evidence-backed facts extracted by the client model from the posting; non-null evidence is a short source excerpt rather than an inference. Fields absent from the source are omitted or null. | |
| experience_months | No | Minimum required experience in months, when stated | |
| work_location_type | No | Work arrangement: on_site, remote, hybrid | |
| education_requirements | No | Education requirements: no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hasMore | No | ||
| totalCount | No | ||
| trackedJob | No | ||
| statusOrder | No | ||
| trackedJobs | No | ||
| trackerWebUrl | No | ||
| subStatusOrder | No |