canonical: https://jentic.com/apis/homerun.co/homerun # Homerun Public API Jentic publishes the only available OpenAPI specification for Homerun Public API, keeping it validated and agent-ready. The Homerun Public API gives programmatic access to vacancies, job applications, application notes, and applicant files inside a Homerun applicant tracking workspace. It uses scope-based bearer tokens so each integration can be limited to read-only or write access on specific resources. Useful for sourcing automations, candidate sync into a data warehouse, or AI assistants that triage incoming applications. ## For AI agents Read vacancies and job applications, attach notes and files, and triage candidates inside a Homerun ATS workspace. ## Scope Does not handle payroll, employee onboarding, or interview scheduling - use for managing Homerun vacancies, job applications, notes, and files only. ## Capabilities - List open vacancies and pull detailed vacancy descriptions for sourcing agents - Create new job applications when candidates arrive from external sources - Update job application properties such as stage or status as candidates progress - Attach interview notes and feedback to specific job applications - Upload resumes and applicant photos to a job application record - Test bearer token validity via the ping endpoint before running batch jobs ## Use cases ### Sync Homerun Candidates to a Data Warehouse Mirror Homerun job applications and vacancies into a data warehouse for analytics on hiring funnel velocity, source-of-hire, and time-to-fill. The agent paginates GET /job-applications and GET /vacancies on a schedule and writes the records downstream. Bearer scopes can be locked to read-only so the integration cannot modify ATS data. Example prompt: Page through GET /job-applications with perPage=100 and load all records updated in the last 24 hours into a Snowflake table. ### Inbound Candidate Triage Assistant Run an AI triage assistant that reads new Homerun job applications, scores them against the vacancy requirements, and posts a structured note back onto the application. The agent calls GET `/job-applications/{id}`, generates a triage summary, and POSTs it to the notes endpoint. Reduces recruiter screening time on high-volume roles. Example prompt: Fetch a new job application, generate a 3-bullet fit assessment, and create a note via POST `/job-applications/{id}/notes.` ### Referral Pipeline Capture Capture employee referrals from a Slack form or referral portal and create matching applications in Homerun. The agent calls POST /job-applications with the candidate details and uploads the resume via POST `/job-applications/{id}/files.` Keeps referrals from getting lost in DMs and ensures they land in the structured pipeline. Example prompt: Create a new application against vacancy_id 12345 with the referrer's notes, then upload the candidate's resume PDF. ### AI Hiring Agent via Jentic Give an AI hiring agent access to Homerun through Jentic so it can list vacancies, read applications, and add notes without you maintaining a custom client. Jentic manages the bearer token in its vault and exposes each Homerun operation via intent search, so the agent finds the right call from natural language. Example prompt: Search Jentic for 'list vacancies', load the schema, execute against Homerun, and return open roles with their application counts. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/job-applications` | List job applications with pagination | | POST | `/job-applications` | Create a new job application | | PATCH | `/job-applications/{job_application_id}` | Update properties on an application | | POST | `/job-applications/{job_application_id}/notes` | Add a note to an application | | POST | `/job-applications/{job_application_id}/files` | Upload files to an application | | GET | `/vacancies` | List open vacancies | | GET | `/vacancies/{vacancy_id}` | Get vacancy details | ## Key resources - **Vacancies** — List and retrieve job openings with role, location type, and candidate counts. - **Job Applications** — Create, read, update, and delete candidate applications attached to a vacancy. - **Job Application Notes** — Append structured recruiter notes to a candidate's application record. - **Job Application Files** — Upload resumes and applicant photos against a job application. ## Why Jentic - **Setup:** Wiring Homerun by hand means setting up its bearer auth, tracking the api.homerun.co/v2 host across vacancies and job-application endpoints, and handling errors yourself. Through Jentic you install once, import the Homerun Public API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Homerun puts the job application id in the URL path (`/job-applications/{job_application_id}/...`), so a rule can pin your agent to one application: it can add notes and files for that application and nothing else. You choose the operations it may call, so writes like patching or creating applications are not included unless you add them. - **Credential handling:** Your Homerun bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list job applications' or 'add a note to an application', and Jentic returns the matching Homerun operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Greenhouse Harvest API** — Larger ATS used by mid-market and enterprise teams with deeper interview workflow primitives. - **Workable API** — ATS focused on SMB hiring with similar vacancy and candidate primitives to Homerun. - **Lever API** — CRM-style ATS with strong sourcing pipelines as an alternative recruiting platform. - **HrFlow.ai API** — Adds AI resume parsing and candidate-job matching scores on top of an existing ATS. ## FAQ ### Why is there no official OpenAPI spec for Homerun Public API? Homerun does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Homerun Public API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Homerun Public API use? Bearer authentication with a scoped API key generated on the Homerun Integrations page. Scopes include vacancies:read, job-applications:read, job-applications:write, and file/note write scopes. Jentic stores the key encrypted and injects it at execution time. ### Can I create job applications with the Homerun Public API? Yes. POST /job-applications creates a new application, and you can immediately attach notes via POST `/job-applications/{id}/notes` or upload resumes via POST `/job-applications/{id}/files.` Your bearer token must include the job-applications:write scope. ### What are the rate limits for the Homerun Public API? Homerun enforces 60 requests per minute per API key. Plan paginated reads (perPage up to 100) and back off on 429 responses. For large historical exports, run jobs in smaller batches and persist a cursor. ### How do I update a job application stage with the Homerun Public API through Jentic? Run pip install jentic, search for 'update job application', load the PATCH `/job-applications/{job_application_id}` schema, and execute with the application id and new field values. Jentic handles the bearer auth automatically. ### Can I read vacancy details and candidate counts in one call? Yes. GET `/vacancies/{vacancy_id}` returns the full vacancy record. To include the total candidate count, pass include[]=total_candidate_count as a query parameter - the field is optional and only returned when requested. ### Can I limit what my agent is allowed to do with the Homerun Public API? Yes. Because you run Jentic One yourself, you decide which Homerun operations your agent may call, so writes like PATCH `/job-applications/{job_application_id}` or POST /job-applications are excluded unless you add them. Since Homerun puts the application id in the URL path, your rules can pin the agent to a single application so it can only add notes via POST `/job-applications/{job_application_id}/notes` and upload files via the matching files endpoint. The bearer token is held by your own instance and injected at execution time, and the agent never sees operations you have not granted.