application_change_stage

Move job applications between interview stages in the Ashby hiring pipeline to track candidate progress and manage recruitment workflows.

Instructions

Move an application to a different interview stage.

Input Schema

TableJSON Schema

Name	Required	Description
`applicationId`	Yes	The application ID
`interviewStageId`	Yes	Target interview stage ID
`archiveReasonId`	No	Required when moving to an Archived stage

Implementation Reference

src/ashby/server.py:407-434 (handler)

The `handle_call_tool` function serves as the central handler for all MCP tools. It uses the `TOOL_ENDPOINT_MAP` to route tool calls to the corresponding Ashby API endpoint, including 'application_change_stage'.

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
    """Route tool calls to the correct Ashby endpoint, passing arguments directly."""
    endpoint = TOOL_ENDPOINT_MAP.get(name)
    if not endpoint:
        return [types.TextContent(type="text", text=f"Unknown tool: {name}")]

    try:
        # Pass arguments straight through -- tool schemas already use Ashby's
        # camelCase param names so no translation is needed.
        response = ashby.post(endpoint, data=arguments if arguments else None)
        return [types.TextContent(type="text", text=json.dumps(response, indent=2))]
    except requests.exceptions.HTTPError as e:
        error_body = ""
        if e.response is not None:
            try:
                error_body = e.response.text
            except Exception:
                pass
        return [
            types.TextContent(
                type="text",
                text=f"Ashby API error on {endpoint}: {e}\n{error_body}",
            )
        ]
    except Exception as e:
        return [types.TextContent(type="text", text=f"Error calling {endpoint}: {e}")]

src/ashby/server.py:260-275 (registration)

Registration of the 'application_change_stage' tool within the TOOLS list, including its schema definition.

types.Tool(
    name="application_change_stage",
    description="Move an application to a different interview stage.",
    inputSchema={
        "type": "object",
        "properties": {
            "applicationId": {"type": "string", "description": "The application ID"},
            "interviewStageId": {"type": "string", "description": "Target interview stage ID"},
            "archiveReasonId": {
                "type": "string",
                "description": "Required when moving to an Archived stage",
            },
        },
        "required": ["applicationId", "interviewStageId"],
    },
),

src/ashby/server.py:374-399 (helper)

The `TOOL_ENDPOINT_MAP` dictionary maps the 'application_change_stage' tool name to the '/application.change_stage' Ashby API endpoint.

TOOL_ENDPOINT_MAP = {
    "job_list": "/job.list",
    "job_info": "/job.info",
    "job_search": "/job.search",
    "candidate_list": "/candidate.list",
    "candidate_search": "/candidate.search",
    "candidate_info": "/candidate.info",
    "candidate_create": "/candidate.create",
    "candidate_create_note": "/candidate.createNote",
    "candidate_list_notes": "/candidate.listNotes",
    "candidate_add_tag": "/candidate.addTag",
    "candidate_tag_list": "/candidateTag.list",
    "application_list": "/application.list",
    "application_info": "/application.info",
    "application_create": "/application.create",
    "application_change_stage": "/application.change_stage",
    "interview_stage_list": "/interviewStage.list",
    "interview_plan_list": "/interviewPlan.list",
    "interview_list": "/interview.list",
    "interview_info": "/interview.info",
    "department_list": "/department.list",
    "user_list": "/user.list",
    "source_list": "/source.list",
    "archive_reason_list": "/archiveReason.list",
    "location_list": "/location.list",
}

Ashby MCP Server