Ashbyhq APIjobs.ashbyhq.com ↗

"""
Ashby Job Board API Client
Practical example for interacting with AshbyHQ job boards.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Optional


class ParseClient:
    """Client for interacting with the Parse API for Ashby job boards."""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "fac3e9d6-234c-4bf2-b5aa-36d377c3884e"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict[str, Any]:
        """Make an API call to the Parse endpoint.
        
        Args:
            endpoint: The endpoint name (e.g., 'get_company_info')
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to pass to the endpoint
            
        Returns:
            API response as a dictionary
            
        Raises:
            requests.HTTPError: If the request fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method == "GET":
            response = requests.get(url, headers=headers, params=params, timeout=30)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=params, timeout=30)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()

    def get_company_info(self, company_slug: str) -> dict[str, Any]:
        """Retrieve company-level metadata for an Ashby-hosted job board.
        
        Args:
            company_slug: Company slug as used in the job board URL (e.g., 'ramp')
            
        Returns:
            Company information including name, publicWebsite, theme, and timezone
        """
        result = self._call("get_company_info", method="GET", company_slug=company_slug)
        return result.get("data", {})

    def get_company_job_listings(self, company_slug: str) -> dict[str, Any]:
        """Retrieve all open job postings and teams for a company's job board.
        
        Args:
            company_slug: Company slug as used in the job board URL
            
        Returns:
            Dictionary with 'jobPostings' and 'teams' arrays
        """
        result = self._call("get_company_job_listings", method="GET", company_slug=company_slug)
        return result.get("data", {})

    def get_job_details(self, company_slug: str, job_id: str) -> dict[str, Any]:
        """Retrieve full details of a specific job posting.
        
        Args:
            company_slug: Company slug
            job_id: Job posting ID (UUID format)
            
        Returns:
            Job details including title, description, compensation, and location
        """
        result = self._call("get_job_details", method="GET", company_slug=company_slug, job_id=job_id)
        return result.get("data", {})

    def get_job_application_form(self, company_slug: str, job_id: str) -> dict[str, Any]:
        """Retrieve all application form questions for a specific job posting.
        
        Args:
            company_slug: Company slug
            job_id: Job posting ID (UUID format)
            
        Returns:
            Dictionary with job_id, job_title, and questions array
        """
        result = self._call("get_job_application_form", method="GET", company_slug=company_slug, job_id=job_id)
        return result.get("data", {})

    def search_jobs(self, company_slug: str, query: Optional[str] = None, 
                   department_id: Optional[str] = None) -> list[dict[str, Any]]:
        """Search for jobs within a company board by keyword and/or department.
        
        Args:
            company_slug: Company slug as used in the job board URL
            query: Search keyword to filter job titles (optional, case-insensitive)
            department_id: Team/department ID to filter by (optional)
            
        Returns:
            List of job postings matching the search criteria
        """
        params = {"company_slug": company_slug}
        if query:
            params["query"] = query
        if department_id:
            params["department_id"] = department_id
        result = self._call("search_jobs", method="GET", **params)
        return result.get("data", [])


def main():
    """Practical workflow demonstrating the Ashby Jobs API."""
    # Initialize client
    client = ParseClient()
    
    # Use a sample company
    company_slug = "ramp"
    
    print("=" * 80)
    print("ASHBY JOB BOARD API - PRACTICAL WORKFLOW")
    print("=" * 80)
    
    # Step 1: Get company information
    print(f"\n[1] Fetching company info for '{company_slug}'...")
    try:
        company_info = client.get_company_info(company_slug=company_slug)
        company_name = company_info.get("name", "Unknown")
        company_website = company_info.get("publicWebsite", "N/A")
        company_timezone = company_info.get("timezone", "N/A")
        allow_indexing = company_info.get("allowJobPostIndexing", False)
        
        print(f"    ✓ Company: {company_name}")
        print(f"    ✓ Website: {company_website}")
        print(f"    ✓ Timezone: {company_timezone}")
        print(f"    ✓ Jobs Indexed: {allow_indexing}")
    except Exception as e:
        print(f"    ✗ Error: {e}")
        return
    
    # Step 2: Get all job listings and teams
    print(f"\n[2] Fetching job listings and organizational structure...")
    try:
        listings = client.get_company_job_listings(company_slug=company_slug)
        job_postings = listings.get("jobPostings", [])
        teams = listings.get("teams", [])
        
        print(f"    ✓ Found {len(job_postings)} open positions")
        print(f"    ✓ Found {len(teams)} teams/departments")
        
        if teams:
            print(f"\n    Teams: {', '.join([t['name'] for t in teams[:5]])}")
            if len(teams) > 5:
                print(f"    ... and {len(teams) - 5} more")
        
        # Display sample jobs
        if job_postings:
            print(f"\n    Sample positions available:")
            for i, job in enumerate(job_postings[:5], 1):
                location = job.get("locationName", "Remote")
                comp = job.get("compensationTierSummary", "Not specified")
                print(f"    {i}. {job.get('title')} - {location}")
                print(f"       {comp}")
    except Exception as e:
        print(f"    ✗ Error: {e}")
        return
    
    # Step 3: Search for specific job types
    print(f"\n[3] Searching for 'Engineer' positions...")
    try:
        search_results = client.search_jobs(company_slug=company_slug, query="Engineer")
        
        print(f"    ✓ Found {len(search_results)} matching positions")
        engineer_jobs = search_results[:5]
        
        if engineer_jobs:
            print(f"\n    Matching roles:")
            for i, job in enumerate(engineer_jobs, 1):
                comp = job.get("compensationTierSummary", "Not specified")
                workplace = job.get("workplaceType", "N/A")
                emp_type = job.get("employmentType", "N/A")
                print(f"    {i}. {job.get('title')}")
                print(f"       Location: {job.get('locationName')} | {workplace} | {emp_type}")
                print(f"       Compensation: {comp}")
    except Exception as e:
        print(f"    ✗ Error: {e}")
        return
    
    # Step 4: Get detailed information for selected job
    if engineer_jobs:
        print(f"\n[4] Getting full details for selected role...")
        selected_job = engineer_jobs[0]
        job_id = selected_job.get("id")
        
        try:
            job_details = client.get_job_details(company_slug=company_slug, job_id=job_id)
            
            print(f"    ✓ Job ID: {job_details.get('id')}")
            print(f"    ✓ Title: {job_details.get('title')}")
            print(f"    ✓ Department: {job_details.get('departmentName', 'N/A')}")
            print(f"    ✓ Primary Location: {job_details.get('locationName')}")
            print(f"    ✓ Employment Type: {job_details.get('employmentType')}")
            print(f"    ✓ Workplace Type: {job_details.get('workplaceType')}")
            print(f"    ✓ Compensation: {job_details.get('compensationTierSummary', 'N/A')}")
            
            secondary_locs = job_details.get("secondaryLocationNames", [])
            if secondary_locs:
                print(f"    ✓ Secondary Locations: {', '.join(secondary_locs)}")
            
            team_names = job_details.get("teamNames", [])
            if team_names:
                print(f"    ✓ Team Hierarchy: {' → '.join(team_names)}")
            
            deadline = job_details.get("applicationDeadline")
            if deadline:
                print(f"    ✓ Application Deadline: {deadline}")
            
            # Step 5: Get application form requirements
            print(f"\n[5] Fetching application form requirements...")
            form_data = client.get_job_application_form(company_slug=company_slug, job_id=job_id)
            questions = form_data.get("questions", [])
            
            print(f"    ✓ Application form has {len(questions)} fields")
            
            required_fields = [q for q in questions if q.get("required")]
            optional_fields = [q for q in questions if not q.get("required")]
            
            if required_fields:
                print(f"\n    Required fields ({len(required_fields)}):")
                for q in required_fields[:8]:
                    field_type = q.get("type", "Unknown")
                    print(f"    • {q.get('label')} ({field_type})")
                if len(required_fields) > 8:
                    print(f"    ... and {len(required_fields) - 8} more")
            
            if optional_fields:
                print(f"\n    Optional fields ({len(optional_fields)}):")
                for q in optional_fields[:5]:
                    field_type = q.get("type", "Unknown")
                    print(f"    • {q.get('label')} ({field_type})")
                if len(optional_fields) > 5:
                    print(f"    ... and {len(optional_fields) - 5} more")
        
        except Exception as e:
            print(f"    ✗ Error: {e}")
            return
    
    # Step 6: Filter jobs by department
    if teams:
        print(f"\n[6] Filtering jobs by department...")
        sample_team = teams[0]
        team_id = sample_team.get("id")
        team_name = sample_team.get("name")
        
        try:
            dept_jobs = client.search_jobs(company_slug=company_slug, department_id=team_id)
            print(f"    ✓ Found {len(dept_jobs)} positions in '{team_name}' department")
            
            if dept_jobs:
                print(f"\n    Positions in {team_name}:")
                for i, job in enumerate(dept_jobs[:5], 1):
                    print(f"    {i}. {job.get('title')} ({job.get('workplaceType')})")
                if len(dept_jobs) > 5:
                    print(f"    ... and {len(dept_jobs) - 5} more")
        except Exception as e:
            print(f"    ✗ Error: {e}")
    
    # Step 7: Multi-criteria search
    print(f"\n[7] Advanced search: 'Manager' in Sales department...")
    try:
        sales_team = next((t for t in teams if "sales" in t.get("name", "").lower()), None)
        if sales_team:
            manager_sales = client.search_jobs(
                company_slug=company_slug,
                query="Manager",
                department_id=sales_team.get("id")
            )
            print(f"    ✓ Found {len(manager_sales)} Manager positions in {sales_team.get('name')}")
            if manager_sales:
                for job in manager_sales[:3]:
                    print(f"    • {job.get('title')}")
        else:
            print(f"    ! No sales team found in organization")
    except Exception as e:
        print(f"    ✗ Error: {e}")
    
    print("\n" + "=" * 80)
    print("Workflow completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()