The agent that turns websites into APIs!
"""
Ashby ATS API Client - Reverse Engineered from HAR Analysis
===========================================================
This client provides programmatic access to Ashby's public job board APIs,
specifically for retrieving job postings from companies using Ashby as their ATS.
Original Use Case: Fetching all jobs from OpenAI's career page
HAR Analysis Date: 2024
API Base URL: https://jobs.ashbyhq.com/api/non-user-graphql
Authentication: None required (public API)
"""
from typing import Dict, List, Optional, Any
from dataclasses import dataclass
import requests
import json
from enum import Enum
try:
import brotli
HAS_BROTLI = True
except ImportError:
HAS_BROTLI = False
class WorkplaceType(str, Enum):
"""Employment workplace type enumeration."""
HYBRID = "Hybrid"
REMOTE = "Remote"
ONSITE = "Onsite"
class EmploymentType(str, Enum):
"""Employment type enumeration."""
FULL_TIME = "FullTime"
PART_TIME = "PartTime"
CONTRACT = "Contract"
INTERNSHIP = "Internship"
class GeoLocationType(str, Enum):
"""Geographic location type enumeration."""
COUNTRY = "Country"
REGION = "Region"
CITY = "City"
@dataclass
class Team:
"""Represents an organizational team."""
id: str
name: str
external_name: Optional[str]
parent_team_id: Optional[str]
@dataclass
class JobPosting:
"""Represents a job posting summary."""
id: str
title: str
team_id: str
location_id: str
location_name: str
workplace_type: str
employment_type: str
compensation_tier_summary: Optional[str]
secondary_locations: List[Dict[str, str]]
@dataclass
class JobPostingDetails:
"""Represents detailed job posting information."""
id: str
title: str
department_name: str
department_external_name: Optional[str]
location_name: str
location_address: Optional[str]
workplace_type: str
employment_type: str
description_html: str
is_listed: bool
is_confidential: bool
team_names: List[str]
secondary_location_names: List[str]
compensation_tier_summary: Optional[str]
compensation_tiers: List[Dict[str, Any]]
application_deadline: Optional[str]
compensation_tier_guide_url: Optional[str]
scrapeable_compensation_salary_summary: Optional[str]
compensation_philosophy_html: Optional[str]
application_limit_callout_html: Optional[str]
application_form: Dict[str, Any]
survey_forms: List[Dict[str, Any]]
@dataclass
class Organization:
"""Represents organization metadata and branding."""
name: str
public_website: str
hosted_jobs_page_slug: str
allow_job_post_indexing: bool
timezone: str
theme: Dict[str, Any]
active_feature_flags: List[str]
class AshbyAPIClient:
"""
Client for interacting with Ashby's public job board GraphQL API.
This client provides methods to:
- Fetch organization metadata
- List all jobs and teams for an organization
- Get detailed job posting information
- Autocomplete geographic locations for application forms
Example:
>>> client = AshbyAPIClient()
>>> jobs = client.get_job_board("openai")
>>> print(f"Found {len(jobs['jobPostings'])} jobs at {jobs['organization']['name']}")
"""
BASE_URL = "https://jobs.ashbyhq.com/api/non-user-graphql"
# Apollo GraphQL client headers (mimics frontend behavior)
DEFAULT_HEADERS = {
"apollographql-client-name": "frontend_non_user",
"apollographql-client-version": "0.1.0",
"content-type": "application/json",
"accept": "*/*",
"accept-encoding": "gzip, deflate, br",
"accept-language": "en-US,en;q=0.9",
"origin": "https://jobs.ashbyhq.com",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
}
def __init__(self, timeout: int = 30):
"""
Initialize the Ashby API client.
Args:
timeout: Request timeout in seconds (default: 30)
"""
self.timeout = timeout
self.session = requests.Session()
self.session.headers.update(self.DEFAULT_HEADERS)
def _make_request(
self,
operation_name: str,
query: str,
variables: Dict[str, Any],
referer: Optional[str] = None,
) -> Dict[str, Any]:
"""
Make a GraphQL request to the Ashby API.
Args:
operation_name: GraphQL operation name
query: GraphQL query string
variables: Query variables
referer: Optional referer URL for the request
Returns:
Parsed JSON response data
Raises:
requests.exceptions.RequestException: On network errors
ValueError: On invalid JSON responses or GraphQL errors
"""
url = f"{self.BASE_URL}?op={operation_name}"
headers = {}
if referer:
headers["referer"] = referer
payload = {
"operationName": operation_name,
"variables": variables,
"query": query,
}
try:
response = self.session.post(
url, json=payload, headers=headers, timeout=self.timeout
)
response.raise_for_status()
# Check if response has content
if not response.content:
raise ValueError(
f"Empty response from {operation_name}. "
f"Status: {response.status_code}, URL: {url}"
)
content_encoding = response.headers.get("content-encoding", "").lower()
content_type = response.headers.get("content-type", "").lower()
# Try parsing JSON first (requests may have already decompressed it)
# Only manually decompress if parsing fails and content-encoding indicates compression
response_data = None
# Ensure proper encoding for text-based parsing
if response.encoding is None or response.encoding == "ISO-8859-1":
response.encoding = "utf-8"
# First, try parsing JSON directly (works if requests auto-decompressed)
try:
response_data = response.json()
except (json.JSONDecodeError, requests.exceptions.JSONDecodeError):
# JSON parsing failed - might need manual decompression
if content_encoding == "br" and HAS_BROTLI:
content_bytes = response.content
try:
# Try brotli decompression
decompressed = brotli.decompress(content_bytes)
response_data = json.loads(decompressed.decode("utf-8"))
except Exception:
# Decompression failed - content might already be decompressed
# Try parsing the raw content as JSON
try:
response_data = json.loads(content_bytes.decode("utf-8"))
except Exception as e:
raise ValueError(
f"Failed to parse JSON response from {operation_name}. "
f"Status: {response.status_code}, "
f"Content-Encoding: {content_encoding}, "
f"Error: {str(e)}"
) from e
elif content_encoding == "br" and not HAS_BROTLI:
raise ValueError(
f"Response is compressed with brotli but brotli library is not installed. "
f"Install it with: pip install brotli"
)
else:
# Not brotli or parsing failed for other reason
try:
response_text = response.text[:500]
except Exception:
response_text = (
response.content[:500]
if isinstance(response.content, bytes)
else str(response.content)[:500]
)
raise ValueError(
f"Invalid JSON response from {operation_name}. "
f"Status: {response.status_code}, "
f"Content-Type: {content_type}, "
f"Content-Encoding: {content_encoding}, "
f"Response preview: {response_text}"
)
# Check content type if we successfully parsed JSON
if (
response_data is not None
and content_type
and "application/json" not in content_type
):
# Warn but don't fail - we already have valid JSON
pass
# At this point, response_data should be set if we got here
# (otherwise an exception would have been raised)
data = response_data
# Check for GraphQL errors
if "errors" in data:
error_messages = [e.get("message", str(e)) for e in data["errors"]]
raise ValueError(f"GraphQL errors: {', '.join(error_messages)}")
return data.get("data", {})
except requests.exceptions.Timeout:
raise requests.exceptions.Timeout(
f"Request to {operation_name} timed out after {self.timeout}s"
)
except ValueError as e:
# Re-raise ValueError as-is (these are our custom errors)
raise
except requests.exceptions.RequestException as e:
raise requests.exceptions.RequestException(
f"Request to {operation_name} failed: {str(e)}"
)
def get_organization_info(
self, organization_slug: str, search_context: str = "JobBoard"
) -> Organization:
"""
Fetch organization metadata, branding, and configuration.
This endpoint returns:
- Organization name and public website
- Theme configuration (colors, logos, branding)
- Feature flags and settings
- Timezone information
Args:
organization_slug: The organization's job board slug (e.g., "openai")
search_context: Search context (default: "JobBoard")
Returns:
Organization object with metadata
Example:
>>> client = AshbyAPIClient()
>>> org = client.get_organization_info("openai")
>>> print(f"Company: {org.name}")
>>> print(f"Website: {org.public_website}")
>>> print(f"Timezone: {org.timezone}")
"""
query = """
query ApiOrganizationFromHostedJobsPageName($organizationHostedJobsPageName: String!, $searchContext: OrganizationSearchContext) {
organization: organizationFromHostedJobsPageName(
organizationHostedJobsPageName: $organizationHostedJobsPageName
searchContext: $searchContext
) {
...OrganizationParts
__typename
}
}
fragment OrganizationParts on Organization {
name
publicWebsite
customJobsPageUrl
hostedJobsPageSlug
allowJobPostIndexing
theme {
colors
showJobFilters
showLocationAddress
showTeams
showAutofillApplicationsBox
logoWordmarkImageUrl
logoSquareImageUrl
applicationSubmittedSuccessMessage
jobBoardTopDescriptionHtml
jobBoardBottomDescriptionHtml
jobPostingBackUrl
__typename
}
appConfirmationTrackingPixelHtml
recruitingPrivacyPolicyUrl
activeFeatureFlags
timezone
candidateScheduleCancellationReasonRequirementStatus
__typename
}
"""
variables = {
"organizationHostedJobsPageName": organization_slug,
"searchContext": search_context,
}
referer = f"https://jobs.ashbyhq.com/{organization_slug}"
data = self._make_request(
"ApiOrganizationFromHostedJobsPageName", query, variables, referer
)
org_data = data.get("organization", {})
return Organization(
name=org_data.get("name"),
public_website=org_data.get("publicWebsite"),
hosted_jobs_page_slug=org_data.get("hostedJobsPageSlug"),
allow_job_post_indexing=org_data.get("allowJobPostIndexing"),
timezone=org_data.get("timezone"),
theme=org_data.get("theme", {}),
active_feature_flags=org_data.get("activeFeatureFlags", []),
)
def get_job_board_with_teams(self, organization_slug: str) -> Dict[str, Any]:
"""
Fetch complete job board including all teams and job postings.
This is the primary endpoint for retrieving all available jobs at an organization.
Returns both the organizational team structure and a list of all job postings.
Args:
organization_slug: The organization's job board slug (e.g., "openai")
Returns:
Dictionary containing:
- teams: List of Team objects with hierarchy
- jobPostings: List of JobPosting summaries
Example:
>>> client = AshbyAPIClient()
>>> board = client.get_job_board_with_teams("openai")
>>> print(f"Teams: {len(board['teams'])}")
>>> print(f"Open positions: {len(board['jobPostings'])}")
>>>
>>> for job in board['jobPostings']:
>>> print(f"{job['title']} - {job['locationName']} ({job['workplaceType']})")
>>> if job['compensationTierSummary']:
>>> print(f" Compensation: {job['compensationTierSummary']}")
"""
query = """
query ApiJobBoardWithTeams($organizationHostedJobsPageName: String!) {
jobBoard: jobBoardWithTeams(
organizationHostedJobsPageName: $organizationHostedJobsPageName
) {
teams {
id
name
externalName
parentTeamId
__typename
}
jobPostings {
id
title
teamId
locationId
locationName
workplaceType
employmentType
secondaryLocations {
...JobPostingSecondaryLocationParts
__typename
}
compensationTierSummary
__typename
}
__typename
}
}
fragment JobPostingSecondaryLocationParts on JobPostingSecondaryLocation {
locationId
locationName
__typename
}
"""
variables = {"organizationHostedJobsPageName": organization_slug}
referer = f"https://jobs.ashbyhq.com/{organization_slug}"
data = self._make_request("ApiJobBoardWithTeams", query, variables, referer)
return data.get("jobBoard", {})
def get_job_posting_details(
self, organization_slug: str, job_posting_id: str
) -> JobPostingDetails:
"""
Fetch detailed information for a specific job posting.
This endpoint returns:
- Full job description HTML
- Complete compensation information
- Application form structure and fields
- Team and location details
- EEOC survey forms
Args:
organization_slug: The organization's job board slug (e.g., "openai")
job_posting_id: The unique job posting ID
Returns:
JobPostingDetails object with complete job information
Example:
>>> client = AshbyAPIClient()
>>> job = client.get_job_posting_details("openai", "73eb1b69-095d-4f27-84ba-54f5df9bc230")
>>> print(f"Title: {job.title}")
>>> print(f"Department: {job.department_name}")
>>> print(f"Compensation: {job.compensation_tier_summary}")
>>> print(f"\\nDescription:\\n{job.description_html}")
>>>
>>> # Access application form fields
>>> for section in job.application_form['sections']:
>>> for field in section['fieldEntries']:
>>> print(f"Field: {field['field']['title']} (Required: {field['isRequired']})")
"""
query = """
query ApiJobPosting($organizationHostedJobsPageName: String!, $jobPostingId: String!) {
jobPosting(
organizationHostedJobsPageName: $organizationHostedJobsPageName
jobPostingId: $jobPostingId
) {
id
title
departmentName
departmentExternalName
locationName
locationAddress
workplaceType
employmentType
descriptionHtml
isListed
isConfidential
teamNames
applicationForm {
...FormRenderParts
__typename
}
surveyForms {
...FormRenderParts
__typename
}
secondaryLocationNames
compensationTierSummary
compensationTiers {
id
title
tierSummary
__typename
}
applicationDeadline
compensationTierGuideUrl
scrapeableCompensationSalarySummary
compensationPhilosophyHtml
applicationLimitCalloutHtml
shouldAskForTextingConsent
candidateTextingPrivacyPolicyUrl
legalEntityNameForTextingConsent
automatedProcessingLegalNotice {
automatedProcessingLegalNoticeRuleId
automatedProcessingLegalNoticeHtml
__typename
}
__typename
}
}
fragment JSONBoxParts on JSONBox {
value
__typename
}
fragment FileParts on File {
id
filename
__typename
}
fragment FormFieldEntryParts on FormFieldEntry {
id
field
fieldValue {
... on JSONBox {
...JSONBoxParts
__typename
}
... on File {
...FileParts
__typename
}
... on FileList {
files {
...FileParts
__typename
}
__typename
}
__typename
}
isRequired
descriptionHtml
isHidden
__typename
}
fragment FormRenderParts on FormRender {
id
formControls {
identifier
title
__typename
}
errorMessages
sections {
title
descriptionHtml
fieldEntries {
...FormFieldEntryParts
__typename
}
isHidden
__typename
}
sourceFormDefinitionId
__typename
}
"""
variables = {
"organizationHostedJobsPageName": organization_slug,
"jobPostingId": job_posting_id,
}
referer = f"https://jobs.ashbyhq.com/{organization_slug}/{job_posting_id}"
data = self._make_request("ApiJobPosting", query, variables, referer)
job_data = data.get("jobPosting", {})
return JobPostingDetails(
id=job_data.get("id"),
title=job_data.get("title"),
department_name=job_data.get("departmentName"),
department_external_name=job_data.get("departmentExternalName"),
location_name=job_data.get("locationName"),
location_address=job_data.get("locationAddress"),
workplace_type=job_data.get("workplaceType"),
employment_type=job_data.get("employmentType"),
description_html=job_data.get("descriptionHtml"),
is_listed=job_data.get("isListed"),
is_confidential=job_data.get("isConfidential"),
team_names=job_data.get("teamNames", []),
secondary_location_names=job_data.get("secondaryLocationNames", []),
compensation_tier_summary=job_data.get("compensationTierSummary"),
compensation_tiers=job_data.get("compensationTiers", []),
application_deadline=job_data.get("applicationDeadline"),
compensation_tier_guide_url=job_data.get("compensationTierGuideUrl"),
scrapeable_compensation_salary_summary=job_data.get(
"scrapeableCompensationSalarySummary"
),
compensation_philosophy_html=job_data.get("compensationPhilosophyHtml"),
application_limit_callout_html=job_data.get("applicationLimitCalloutHtml"),
application_form=job_data.get("applicationForm", {}),
survey_forms=job_data.get("surveyForms", []),
)
def autocomplete_location(
self, text: str, location_types: Optional[List[GeoLocationType]] = None
) -> List[Dict[str, Any]]:
"""
Autocomplete geographic locations for application forms.
This endpoint provides location suggestions as users type into location fields
during the job application process.
Args:
text: Search text to autocomplete (minimum 1 character)
location_types: List of location types to search for
(default: [Country, Region, City])
Returns:
List of location suggestions with geographic hierarchy
Example:
>>> client = AshbyAPIClient()
>>> suggestions = client.autocomplete_location("San Fr")
>>> for suggestion in suggestions:
>>> print(f"{suggestion['name']}")
>>> for geo in suggestion['geoLocationPath']:
>>> print(f" - {geo['name']} ({geo['type']})")
"""
if location_types is None:
location_types = [
GeoLocationType.COUNTRY,
GeoLocationType.REGION,
GeoLocationType.CITY,
]
query = """
query ApiAutocompleteGeoLocation($text: String!, $locationTypes: [GeoLocationType!]) {
result: autocompleteGeoLocation(text: $text, locationTypes: $locationTypes) {
...AutocompleteLocationResultParts
__typename
}
}
fragment AutocompleteGeoLocationParts on GeoLocation {
name
type
providerLocationId
__typename
}
fragment AutocompleteLocationParts on AutocompleteLocation {
name
geoLocationPath {
...AutocompleteGeoLocationParts
__typename
}
__typename
}
fragment AutocompleteLocationResultParts on AutocompleteLocationResult {
suggestions {
...AutocompleteLocationParts
__typename
}
__typename
}
"""
variables = {"text": text, "locationTypes": [lt.value for lt in location_types]}
data = self._make_request("ApiAutocompleteGeoLocation", query, variables)
result = data.get("result", {})
return result.get("suggestions", [])
def get_all_jobs(self, organization_slug: str) -> List[Dict[str, Any]]:
"""
Convenience method to fetch all jobs for an organization.
This is a high-level helper that combines organization info and job board data.
Args:
organization_slug: The organization's job board slug (e.g., "openai")
Returns:
List of all job postings with basic information
Example:
>>> client = AshbyAPIClient()
>>> jobs = client.get_all_jobs("openai")
>>> print(f"Found {len(jobs)} open positions")
>>>
>>> # Filter by location
>>> sf_jobs = [j for j in jobs if "San Francisco" in j['locationName']]
>>> print(f"{len(sf_jobs)} jobs in San Francisco")
>>>
>>> # Filter by workplace type
>>> remote_jobs = [j for j in jobs if j['workplaceType'] == 'Remote']
>>> print(f"{len(remote_jobs)} remote positions")
"""
board = self.get_job_board_with_teams(organization_slug)
if not board:
return []
return board.get("jobPostings", []) or []
def close(self):
"""Close the HTTP session."""
self.session.close()
def __enter__(self):
"""Context manager entry."""
return self
def __exit__(self, exc_type, exc_val, exc_tb):
"""Context manager exit."""
self.close()
# Example usage and demonstration
if __name__ == "__main__":
# Example 1: Get all jobs from OpenAI
print("=" * 80)
print("Example 1: Fetching all jobs from OpenAI")
print("=" * 80)
with AshbyAPIClient() as client:
# Get organization info
org = client.get_organization_info("openai")
print(f"\nCompany: {org.name}")
print(f"Website: {org.public_website}")
print(f"Timezone: {org.timezone}")
print(f"Job Indexing Allowed: {org.allow_job_post_indexing}")
# Get all jobs
jobs = client.get_all_jobs("openai")
print(f"\nFound {len(jobs)} open positions at {org.name}")
# Display summary statistics
workplace_types = {}
locations = {}
for job in jobs:
# Count by workplace type
wt = job.get("workplaceType", "Unknown")
workplace_types[wt] = workplace_types.get(wt, 0) + 1
# Count by location
loc = job.get("locationName", "Unknown")
locations[loc] = locations.get(loc, 0) + 1
print("\nBreakdown by Workplace Type:")
for wt, count in sorted(
workplace_types.items(), key=lambda x: x[1], reverse=True
):
print(f" {wt}: {count}")
print("\nTop Locations:")
for loc, count in sorted(locations.items(), key=lambda x: x[1], reverse=True)[
:5
]:
print(f" {loc}: {count}")
# Display first 5 jobs
print("\n" + "=" * 80)
print("Sample Job Listings (first 5):")
print("=" * 80)
for i, job in enumerate(jobs[:5], 1):
print(f"\n{i}. {job['title']}")
print(f" Location: {job['locationName']} ({job['workplaceType']})")
print(f" Team ID: {job['teamId']}")
if job.get("compensationTierSummary"):
print(f" Compensation: {job['compensationTierSummary']}")
if job.get("secondaryLocations"):
sec_locs = [sl["locationName"] for sl in job["secondaryLocations"]]
print(f" Also available in: {', '.join(sec_locs)}")
print("\n" + "=" * 80)
print("Example 2: Get detailed job posting")
print("=" * 80)
with AshbyAPIClient() as client:
# Get first job ID from the list
jobs = client.get_all_jobs("openai")
if jobs:
first_job = jobs[0]
job_id = first_job["id"]
# Fetch detailed information
details = client.get_job_posting_details("openai", job_id)
print(f"\nJob Title: {details.title}")
print(f"Department: {details.department_name}")
print(f"Teams: {', '.join(details.team_names)}")
print(f"Location: {details.location_name}")
print(f"Workplace Type: {details.workplace_type}")
print(f"Employment Type: {details.employment_type}")
if details.compensation_tier_summary:
print(f"Compensation: {details.compensation_tier_summary}")
if details.scrapeable_compensation_salary_summary:
print(f"Salary Range: {details.scrapeable_compensation_salary_summary}")
# Show application form fields
print("\nApplication Form Fields:")
for section in details.application_form.get("sections", []):
for field_entry in section.get("fieldEntries", []):
field = field_entry.get("field", {})
field_title = field.get("title", "Unknown")
is_required = field_entry.get("isRequired", False)
field_type = field.get("type", "Unknown")
required_marker = "*" if is_required else " "
print(f" {required_marker} {field_title} ({field_type})")
# Show description preview (first 500 characters)
if details.description_html:
# Simple HTML tag removal for preview
import re
text_preview = re.sub("<[^<]+?>", "", details.description_html)
text_preview = " ".join(text_preview.split())[:500]
print(f"\nJob Description Preview:")
print(f"{text_preview}...")
print("\n" + "=" * 80)
print("Example 3: Location autocomplete")
print("=" * 80)
with AshbyAPIClient() as client:
suggestions = client.autocomplete_location("San Francisco")
print(f"\nLocation suggestions for 'San Francisco':")
for suggestion in suggestions[:5]:
print(f"\n {suggestion['name']}")
for geo in suggestion.get("geoLocationPath", []):
print(f" - {geo['name']} ({geo['type']})")
print("\n" + "=" * 80)
print("All examples completed successfully!")
print("=" * 80)