Homerun MCP by usefulapi

List job vacancies (draft, private, public, ...) with title, status, type, location type and expiry. Optionally include location, department, hiring stages (their ids are what homerun_move_application_to_stage needs), salary indication and the candidate count. GET /vacancies (scope vacancies:read).

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Only vacancies in these statuses, e.g. [\"public\",\"private\"] or [\"draft\"].",
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z_]{2,30}$"
      }
    },
    "include": {
      "description": "Extra data to include. Use stages to see the hiring stage ids.",
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "location",
          "department",
          "stages",
          "salaryIndication",
          "total_candidate_count"
        ]
      }
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "perPage": {
      "description": "Results per page, 1-100 (default 15).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One vacancy by id with description, location, department, hiring stages (id + name), salary indication, candidate count and the public job and application-form URLs. GET /vacancies/{vacancy_id} (scope vacancies:read).

{
  "type": "object",
  "properties": {
    "vacancy_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Vacancy id, e.g. job_SnhUsAg1QwTRFIRNUfM6."
    }
  },
  "required": [
    "vacancy_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List job applications, newest page first as the API orders them. Each item has name, e-mail, vacancy id, current stage (id + name), rating, created/hired dates and disqualified flag. Personal data: no phone number, date of birth, photo or files are returned here; ask for one application with homerun_get_application. Filter by vacancy, stage name or disqualified state and page through; do not use it to export all candidates. GET /job-applications (scope job-applications:read).

{
  "type": "object",
  "properties": {
    "vacancy_id": {
      "description": "Only applications of these vacancy ids (filter[vacancy_id]).",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,64}$",
        "description": "Vacancy id"
      }
    },
    "stage": {
      "description": "Only applications in the hiring stage with this name (stage names belong to a vacancy, so combine with vacancy_id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "disqualified": {
      "description": "true = only disqualified, false = only not disqualified.",
      "type": "boolean"
    },
    "hired_after": {
      "description": "Only applicants hired after this date, yyyy-mm-dd.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "include_sources": {
      "description": "Also return the sources (e.g. Homerun Career Page, Indeed) of each application.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "perPage": {
      "description": "Results per page, 1-100 (default 15).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One job application in full: contact details (name, e-mail, phone, city, country), links, experience/education, current stage, rating, sources and file names (notes: use homerun_list_notes). Date of birth, photo URL and file download links are never returned. Optionally include the answers to the application-form questions. Personal data: fetch only the candidate you need. GET /job-applications/{job_application_id} (scope job-applications:read).

{
  "type": "object",
  "properties": {
    "job_application_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Application id, e.g. ap_D3kCkoClbG6n6KlqD0ob."
    },
    "include_answers": {
      "description": "Also return the application-form questions and the candidate's answers.",
      "type": "boolean"
    }
  },
  "required": [
    "job_application_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the notes on one application: id, author display name, text, sensitive flag and timestamps. GET /job-applications/{job_application_id}/notes (scope job-application-notes:read).

{
  "type": "object",
  "properties": {
    "job_application_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Application id."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "perPage": {
      "description": "Results per page, 1-100 (default 15).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "required": [
    "job_application_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's candidate tags (id + name). GET /tags (scope tags:read).

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "perPage": {
      "description": "Results per page, 1-100 (default 15).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The tags attached to one application. GET /job-applications/{job_application_id}/tags (scope job-application-tags:read).

{
  "type": "object",
  "properties": {
    "job_application_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Application id."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "perPage": {
      "description": "Results per page, 1-100 (default 15).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "required": [
    "job_application_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: move ONE application to another hiring stage of its vacancy (PATCH with only the stage id; nothing else on the application changes). Get stage ids from homerun_get_vacancy. Homerun's own automations for that stage may run (for example automatic e-mails configured in Homerun); this tool sends no e-mail itself and does not reject or delete anyone. PATCH /job-applications/{job_application_id} (scope job-applications:write).

{
  "type": "object",
  "properties": {
    "job_application_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Application id."
    },
    "stage_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Hiring stage id from the vacancy's stages (homerun_get_vacancy)."
    }
  },
  "required": [
    "job_application_id",
    "stage_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add ONE note (1-2000 characters) to one application. It becomes visible to the hiring team in Homerun and cannot be removed with this server. display_name is free text shown as the author. Nothing is sent to the candidate. POST /job-applications/{job_application_id}/notes (scope job-application-notes:write).

{
  "type": "object",
  "properties": {
    "job_application_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "Application id."
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The note text, 1-2000 characters."
    },
    "display_name": {
      "description": "Author name shown on the note (default \"AI assistant\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 192
    },
    "is_sensitive": {
      "description": "Mark the note as sensitive (restricts who can read it in Homerun).",
      "type": "boolean"
    }
  },
  "required": [
    "job_application_id",
    "note"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}