Skip to main content

Module airbyte_agent_sdk.connectors.greenhouse

Greenhouse connector for Airbyte SDK.

Auto-generated from OpenAPI specification.

Sub-modules​

  • airbyte_agent_sdk.connectors.greenhouse.connector
  • airbyte_agent_sdk.connectors.greenhouse.connector_model
  • airbyte_agent_sdk.connectors.greenhouse.models
  • airbyte_agent_sdk.connectors.greenhouse.types

Classes​

AirbyteAuthConfig(**data: Any) : Authentication configuration for Airbyte hosted mode execution.

Pass this to the connector's auth_config parameter to use hosted mode, where API credentials are stored securely in Airbyte Cloud.

For hosted mode execution, provide client credentials with either:

  • connector_id: Direct connector/source ID (skips lookup)
  • workspace_name: Workspace name for connector lookup

Attributes: workspace_name: Workspace name for hosted mode connector lookup organization_id: Optional Airbyte organization ID for multi-org selection airbyte_client_id: Airbyte OAuth client ID (required for hosted mode) airbyte_client_secret: Airbyte OAuth client secret (required for hosted mode) connector_id: Specific connector/source ID (skips lookup if provided)

Examples:

Hosted mode with connector_id (no lookup needed)

connector = GongConnector( auth_config=AirbyteAuthConfig( airbyte_client_id="client_abc123", airbyte_client_secret="secret_xyz789", connector_id="existing-source-uuid" ) )

Hosted mode with workspace_name (lookup by workspace)

connector = GongConnector( auth_config=AirbyteAuthConfig( workspace_name="user-123", organization_id="00000000-0000-0000-0000-000000000123", airbyte_client_id="client_abc123", airbyte_client_secret="secret_xyz789" ) )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

airbyte_client_id: str | None : The type of the None singleton.

airbyte_client_secret: str | None : The type of the None singleton.

connector_id: str | None : The type of the None singleton.

model_config : The type of the None singleton.

organization_id: str | None : The type of the None singleton.

workspace_name: str | None : The type of the None singleton.

AirbyteSearchMeta(**data: Any) : Pagination metadata for search responses.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

cursor: str | None : Cursor for fetching the next page of results.

has_more: bool : Whether more results are available.

model_config : The type of the None singleton.

took_ms: int | None : Time taken to execute the search in milliseconds.

AirbyteSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel
  • typing.Generic

Descendants​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[ApplicationsSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[CandidatesSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[DepartmentsSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[JobPostsSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[JobsSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[OffersSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[OfficesSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[SourcesSearchData]
  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult[UsersSearchData]

Class variables​

data: list[~D] : List of matching records.

meta: airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchMeta : Pagination metadata.

model_config : The type of the None singleton.

ApplicationsSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

CandidatesSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

DepartmentsSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

JobPostsSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

JobsSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

OffersSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

OfficesSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

SourcesSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

UsersSearchResult(**data: Any) : Result from Airbyte cache search operations with typed records.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • airbyte_agent_sdk.connectors.greenhouse.models.AirbyteSearchResult
  • pydantic.main.BaseModel
  • typing.Generic

ApplicationsSearchData(**data: Any) : Search result data for applications entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

agency_note_id: int | None : Id of the note created when the candidate was submitted by an agency, or null if the application did not come through an agency.

answers: list[typing.Any] | None : Free-text answers the candidate provided on the job post application form. Each entry pairs the question text with the candidate's answer.

candidate_id: int | None : Id of the candidate (person) this application belongs to.

coordinator_id: int | None : Id of the user assigned as coordinator on the application's job, or null when unassigned.

created_at: str | None : Created at from the Greenhouse v3 applications record.

custom_fields: dict[str, typing.Any] | None : Org-defined custom fields keyed by the field's name_key. Each value carries the field's display name, its type, and its value.

id: int | None : Id from the Greenhouse v3 applications record.

job_id: int | None : Id of the job this application is on. null for jobless prospect applications.

job_interview_stage_id: int | None : Id of the job interview stage definition (see GET /v3/job_interview_stages) the candidate is currently in for this application. null for prospect applications and applications in a terminal state.

job_post_id: int | None : Id of the job post the candidate applied through, or null if the application was created internally rather than from a posted role.

last_activity_at: str | None : Timestamp of the most recent activity on this application (notes, emails, stage changes, etc.), in ISO 8601.

location_address: str | None : Free-form location string captured on the application (typically from the job post's location question).

model_config : The type of the None singleton.

needs_decision: bool | None : true when the application is waiting on a hiring-team decision (scorecard completion, advance/reject, etc.) in its current stage.

prospect: bool | None : true for prospect applications (sourced candidates not yet attached to a single job), false for candidate applications on a specific job.

prospective_job_ids: list[typing.Any] | None : For prospect applications, the ids of jobs the prospect is being considered for. Empty for non-prospect applications and for jobless prospects.

recruiter_id: int | None : Id of the user assigned as recruiter on the application's job, or null when unassigned.

referrer_id: int | None : Id of the referrer who credited this application, or null if there was no referral. References a referrer, not a Greenhouse user.

rejected_at: str | None : Timestamp the application was rejected, in ISO 8601. null for applications that have not been rejected.

rejection_reason_id: int | None : Id of the rejection reason selected for the application. References a /v3/rejection_reasons row scoped to the organization. null when the application was rejected without a reason, or has not been rejected.

source_id: int | None : Id of the source the application is attributed to (e.g. a job board, an event, an employee referral source). null if no source is set.

stage_id: int | None : Id of the interview stage the candidate is currently in for this application. null for prospect applications and applications in a terminal state.

stage_name: str | None : Display name of the candidate's current interview stage on this application.

status: str | None : Lifecycle status of the application. in_process for active candidates, rejected for rejected applications, hired once an offer is closed and the hire endpoint has fired, and converted for prospect applications that have been promoted to a candidate application via convert_to_candidate.

updated_at: str | None : Updated at from the Greenhouse v3 applications record.

CandidatesSearchData(**data: Any) : Search result data for candidates entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

addresses: list[typing.Any] | None : Postal addresses on the candidate's profile. Each entry pairs the value with a type such as home, work, or other.

can_email: bool | None : Whether this candidate has consented to receive email communication from your organization.

company: str | None : Candidate's current company, as entered on their profile.

created_at: str | None : Created at from the Greenhouse v3 candidates record.

custom_fields: dict[str, typing.Any] | None : Org-defined custom fields keyed by the field's name_key. Each value carries the field's display name, its type, and its value.

email_addresses: list[typing.Any] | None : Email addresses on the candidate's profile. Each entry pairs the value with a type such as personal, work, or other.

first_name: str | None : First name from the Greenhouse v3 candidates record.

id: int | None : Id from the Greenhouse v3 candidates record.

last_activity_at: str | None : Timestamp of the most recent activity on any of the candidate's applications (notes, emails, stage changes, etc.), in ISO 8601.

last_name: str | None : Last name from the Greenhouse v3 candidates record.

linked_user_ids: list[typing.Any] | None : Ids of Greenhouse users linked to this candidate (employees represented by both a user record and a candidate record).

model_config : The type of the None singleton.

phone_numbers: list[typing.Any] | None : Phone numbers on the candidate's profile. Each entry pairs the value with a type such as mobile, home, work, skype, or other.

preferred_name: str | None : Preferred or chosen name the candidate goes by, when different from their legal first name.

private: bool | None : If true, the candidate is restricted to users with View Private Candidates access. Defaults to false.

social_media_addresses: list[typing.Any] | None : Social media handles or URLs on the candidate's profile. Social entries are untyped — only the value is returned.

tags: list[typing.Any] | None : Candidate tag names applied to this candidate within your organization.

time_zone: str | None : Candidate's time zone as a Rails-style identifier (for example Eastern Time (US & Canada)).

title: str | None : Candidate's current job title, as entered on their profile.

updated_at: str | None : Updated at from the Greenhouse v3 candidates record.

website_addresses: list[typing.Any] | None : Personal websites or portfolio URLs on the candidate's profile. Each entry pairs the value with a type such as personal, company, portfolio, blog, or other.

DepartmentsSearchData(**data: Any) : Search result data for departments entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

created_at: str | None : Created at from the Greenhouse v3 departments record.

external_id: str | None : Partner-supplied identifier for the department, typically the matching id from an HRIS or other external system. Free-form string and null when no external id has been set.

id: int | None : Id from the Greenhouse v3 departments record.

model_config : The type of the None singleton.

name: str | None : Display name of the department (e.g. Engineering, Marketing).

parent_id: int | None : Id of the parent department in the organization's department tree. null for top-level departments. References another /v3/departments row.

updated_at: str | None : Updated at from the Greenhouse v3 departments record.

GreenhouseAuthConfig(**data: Any) : Greenhouse OAuth 2.0

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

access_token: str | None : Access token generated through the Greenhouse OAuth consent flow (optional if refresh_token is provided)

client_id: str : Client ID from the Greenhouse OAuth application

client_secret: str : Client secret from the Greenhouse OAuth application

model_config : The type of the None singleton.

refresh_token: str : Refresh token generated through the Greenhouse OAuth consent flow

GreenhouseConnector(auth_config: GreenhouseAuthConfig | AirbyteAuthConfig | BaseModel | None = None, on_token_refresh: Any | None = None) : Type-safe Greenhouse API connector.

Auto-generated from OpenAPI specification with full type safety.

Initialize a new greenhouse connector instance.

Supports both local and hosted execution modes:

  • Local mode: Provide connector-specific auth config (e.g., GreenhouseAuthConfig)
  • Hosted mode: Provide AirbyteAuthConfig with client credentials and either connector_id or workspace_name

Args: auth_config: Either connector-specific auth config for local mode, or AirbyteAuthConfig for hosted mode on_token_refresh: Optional callback for OAuth2 token refresh persistence. Called with new_tokens dict when tokens are refreshed. Can be sync or async. Example: lambda tokens: save_to_database(tokens) Examples:

Local mode (direct API calls)

connector = GreenhouseConnector(auth_config=GreenhouseAuthConfig(client_id="...", client_secret="...", refresh_token="...", access_token="..."))

Hosted mode with explicit connector_id (no lookup needed)

connector = GreenhouseConnector( auth_config=AirbyteAuthConfig( airbyte_client_id="client_abc123", airbyte_client_secret="secret_xyz789", connector_id="existing-source-uuid" ) )

Hosted mode with lookup by workspace_name

connector = GreenhouseConnector( auth_config=AirbyteAuthConfig( workspace_name="user-123", organization_id="00000000-0000-0000-0000-000000000123", airbyte_client_id="client_abc123", airbyte_client_secret="secret_xyz789" ) )

Class variables​

connector_name : The type of the None singleton.

connector_version : The type of the None singleton.

sdk_version : The type of the None singleton.

Static methods​

agent_tool(role: AgentToolRole | None = None, *, inspect_tool: str | None = None, docs_tool: str | None = None, max_output_chars: int | None | Unset = UNSET, framework: FrameworkName = 'none', internal_retries: int = 0, should_internal_retry: Callable[[Exception, tuple[Any, ...], dict[str, Any]], bool] | None = None, exhausted_runtime_failure_message: Callable[[Exception, tuple[Any, ...], dict[str, Any]], str | None] | None = None) ‑> Callable[[~_F], ~_F] : Framework-agnostic decorator for user-written connector tool functions.

The progressive-docs sibling of tool_utils: instead of baking the full entity/action reference into the docstring, it instructs the agent to call this connector's inspect and docs tools before executing. Tool failures raise :class:airbyte_agent_sdk.AirbyteToolError by default (framework="none", no auto-detection) — pass framework=... to translate to a supported framework's signal instead.

Decorate three functions per connector — execute, inspect and docs. The role is inferred from each function's signature (extra parameters are allowed); a signature matching more than one role, a generic (*args, **kwargs) wrapper, or a callable whose signature cannot be read must pass the role explicitly:

  • (entity, action, ...) -> "execute"
  • (section, ...) -> "read_skill_docs"
  • () -> "inspect_connector"

Usage: connector = GreenhouseConnector(...)

@GreenhouseConnector.agent_tool() async def execute(entity: str, action: str, params: dict | None = None): return await connector.execute(entity=entity, action=action, params=params or {})

@GreenhouseConnector.agent_tool() async def inspect_connector(): return await connector.inspect_connector()

@GreenhouseConnector.agent_tool() async def read_skill_docs(section: str | None = None): return await connector.read_skill_docs(section)

Args: role: "execute" | "inspect_connector" | "read_skill_docs". None (default) infers the role from the decorated function's signature; an explicit role validates the canonical parameters are present (functions accepting **kwargs, or callables whose signature cannot be read, pass validation). inspect_tool: Exact registered name of the sibling inspect tool, woven into the execute docstring for tighter steering. Defaults to generic phrasing. docs_tool: Exact registered name of the sibling docs tool (see inspect_tool). max_output_chars: Max serialized output size before failing. Defaults per role: execute -> DEFAULT_MAX_OUTPUT_CHARS, docs tools -> None. framework: Translation target for tool failures. Defaults to "none" (raise AirbyteToolError); never auto-detects. internal_retries: How many transient runtime failures (429/5xx, network, timeout) to retry silently before surfacing. Forwarded to :func:airbyte_agent_sdk.translation.translate_exceptions. should_internal_retry: Optional predicate (error, args, kwargs) -> bool further restricting which retryable errors are safe for this specific tool. Forwarded to :func:airbyte_agent_sdk.translation.translate_exceptions. exhausted_runtime_failure_message: Optional callback (error, args, kwargs) -> str | None invoked after internal retries are exhausted or skipped. Forwarded to :func:airbyte_agent_sdk.translation.translate_exceptions.

tool_utils(func: _F | None = None, *, update_docstring: bool = True, max_output_chars: int | None = 100000, framework: FrameworkName | None = None, internal_retries: int = 0, should_internal_retry: Callable[[Exception, tuple[Any, ...], dict[str, Any]], bool] | None = None, exhausted_runtime_failure_message: Callable[[Exception, tuple[Any, ...], dict[str, Any]], str | None] | None = None) ‑> ~_F | Callable[[~_F], ~_F] : Add connector-specific documentation and runtime safeguards to one tool.

For new agents, prefer build_connector_tools. It returns progressive inspect_connector, read_skill_docs, and execute tools so the agent can load only the connector guidance it needs:

from airbyte_agent_sdk import build_connector_tools
from pydantic_ai import Agent

tools = build_connector_tools(connector, framework="pydantic_ai")
agent = Agent("openai:gpt-4o", tools=tools.as_list())

Legacy: one generated-description tool​

Existing integrations can keep using tool_utils for one broad execute tool with the connector's full generated catalog in its description:

from fastmcp import FastMCP

connector = GreenhouseConnector()
mcp = FastMCP("Connector Agent")

@mcp.tool()
@GreenhouseConnector.tool_utils
async def execute(entity: str, action: str, params: dict):
    ...

Configure documentation, output limits, framework translation, and retries when needed:

@mcp.tool()
@GreenhouseConnector.tool_utils(update_docstring=False, max_output_chars=None)
async def execute(entity: str, action: str, params: dict):
    ...

@mcp.tool()
@GreenhouseConnector.tool_utils(framework="pydantic_ai", internal_retries=2)
async def execute(entity: str, action: str, params: dict):
    ...

This decorator composes translate_exceptions for runtime wrapping, output-size checks, framework signal translation, and optional internal retries, then adds connector-specific docstring augmentation.

Args: update_docstring: When True, append connector capabilities to __doc__. max_output_chars: Max serialized output size before raising. Use None to disable. framework: One of "pydantic_ai" | "langchain" | "openai_agents" | "mcp". Defaults to None, which auto-detects each framework's canonical import in order. Explicit always wins. internal_retries: How many transient runtime failures (429/5xx, network, timeout) to retry silently before surfacing. Default 0. Forwarded to airbyte_agent_sdk.translation.translate_exceptions. should_internal_retry: Optional predicate (error, args, kwargs) -> bool further restricting which retryable errors are safe for this specific tool. Forwarded to airbyte_agent_sdk.translation.translate_exceptions. exhausted_runtime_failure_message: Optional callback (error, args, kwargs) -> str | None. Invoked after internal retries are exhausted or were skipped because should_internal_retry returned False. Forwarded to airbyte_agent_sdk.translation.translate_exceptions.

Instance variables​

connector_id: str | None : Get the connector/source ID (only available in hosted mode).

Returns: The connector ID if in hosted mode, None if in local mode.

Methods​

check(self) ‑> airbyte_agent_sdk.connectors.greenhouse.models.GreenhouseCheckResult : Perform a health check to verify connectivity and credentials.

Executes a lightweight list operation (limit=1) to validate that the connector can communicate with the API and credentials are valid.

Returns: GreenhouseCheckResult with status ("healthy" or "unhealthy") and optional error message

Example: result = await connector.check() if result.status == "healthy": print("Connection verified!") else: print(f"Check failed: {result.error}")

close(self) : Close the connector and release resources.

entity_schema(self, entity: str) ‑> dict[str, typing.Any] | None : Get the JSON schema for an entity.

Args: entity: Entity name (e.g., "contacts", "companies")

Returns: JSON schema dict describing the entity structure, or None if not found.

Example: schema = connector.entity_schema("contacts") if schema: print(f"Contact properties: {list(schema.get('properties', {}).keys())}")

execute(self, entity: str, action: "Literal['list', 'download', 'context_store_search']", params: Mapping[str, Any] | None = None, *, select_fields: list[str] | None = None, exclude_fields: list[str] | None = None, skip_truncation: bool = True) ‑> Any : Execute an entity operation with full type safety.

This is the recommended interface for blessed connectors as it:

  • Uses the same signature as non-blessed connectors
  • Provides full IDE autocomplete for entity/action/params
  • Makes migration from generic to blessed connectors seamless

Args: entity: Entity name (e.g., "customers") action: Operation action (e.g., "create", "get", "list") params: Operation parameters (typed based on entity+action) select_fields: Optional allowlist of dot-notation fields to include exclude_fields: Optional blocklist of dot-notation fields to remove skip_truncation: Disable long-text truncation for collection actions

Returns: Typed response based on the operation

Example: customer = await connector.execute( entity="customers", action="get", params={"id": "cus_123"} )

inspect_connector(self) ‑> dict[str, typing.Any] : Inspect this connector's hosted metadata/readiness and resolve its docs skill id.

Call this before read_skill_docs in the normal hosted flow. For local/offline connectors this returns a local-mode payload with a warning instead of a hosted inspection.

Example: info = await connector.inspect_connector() print(info["docs_skill_id"])

list_entities(self) ‑> list[dict[str, typing.Any]] : Get structured data about available entities, actions, and parameters.

Returns a list of entity descriptions with:

  • entity_name: Name of the entity (e.g., "contacts", "deals")
  • description: Entity description from the first endpoint
  • available_actions: List of actions (e.g., ["list", "get", "create"])
  • parameters: Dict mapping action -> list of parameter dicts

Example: entities = connector.list_entities() for entity in entities: print(f"{entity['entity_name']}: {entity['available_actions']}")

read_skill_docs(self, section: str | None = None) ‑> str : Read this connector's usage docs, rendered to text.

Omit section for the outline and general guidance; pass an exact section id from the outline for full details. For local/offline connectors the full generated docs are returned and section is ignored.

Example: outline = await connector.read_skill_docs() details = await connector.read_skill_docs(section="entity:contacts")

JobPostsSearchData(**data: Any) : Search result data for job_posts entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

active: bool | None : If true, the post has not been deleted. Deleted posts are excluded by default; pass active=false on the list endpoint to retrieve them.

content: str | None : HTML body of the post shown to candidates on the job board. For internal posts this returns the internal_content instead. Sanitized server-side — only a limited element/attribute allowlist (including iframe, video, source) survives. null while the post is still being scaffolded.

created_at: str | None : Created at from the Greenhouse v3 job posts record.

demographic_question_set_id: int | None : Id of the demographic question set surfaced to candidates on this post for diversity, equity, and inclusion (DE&I) reporting. null when the post does not collect demographic data.

featured: bool | None : If true, the post is currently featured on the organization's internal job board and surfaces in the weekly internal-jobs email. Only internal posts can be featured, and at most three can be featured at a time.

first_published_at: str | None : Timestamp the post first transitioned to live, in ISO 8601. null for posts that have never been published.

id: int | None : Id from the Greenhouse v3 job posts record.

internal: bool | None : If true, the post lives on an internal job board and is visible only to existing employees signed in to the internal board. If false, the post is external and lives on a public-facing job_board. Set by the board the post is associated with at create time.

internal_content: str | None : HTML body shown on the internal job board when the post is also configured as internal. null for external-only posts. Same sanitization rules as content.

job_board_id: int | None : Id of the job_board this post is published to. Resolves to either an external (careers site, syndicated board) or internal job board depending on internal. Each post belongs to exactly one board at a time.

job_id: int | None : Id of the parent job (requisition) this post belongs to. A single job can have multiple posts; the job is the source of truth for the hiring team, openings, and interview plan.

language: str | None : ISO 639-1 locale of the post, used to render the candidate-facing application form in the matching language (e.g. en, fr, ja). null when no locale has been chosen.

live: bool | None : If true, the post is published (job_application_status is live) and its job board is also live. A post on an unpublished board is not live — its public_url returns a 404 until the board is enabled.

model_config : The type of the None singleton.

public_url: str | None : Canonical public URL of the post on its job board, including the gh_jid tracking parameter. null when the post has no associated job board or the board has no public URL configured.

questions: list[typing.Any] | None : Application form questions presented to candidates on this post, including default questions (resume, cover letter, basic info) and any custom questions configured by the hiring team. Ordered as they appear on the form.

title: str | None : Public-facing title shown to candidates on the job board (e.g. Senior Backend Engineer, Remote). Distinct from the internal job.name — a single job can have several posts with different titles, one per board, language, or geography.

updated_at: str | None : Updated at from the Greenhouse v3 job posts record.

JobsSearchData(**data: Any) : Search result data for jobs entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

closed_at: str | None : Timestamp the job most recently transitioned to closed, in ISO 8601. null for jobs that are still open or draft.

confidential: bool | None : If true, the job is restricted to users explicitly granted access on the Hiring Team. The legacy Confidential Jobs feature has been sunset — this flag cannot be set on new jobs and is preserved for jobs that already had it enabled.

copied_from_id: int | None : Id of the job (typically a template) this job was copied from on creation. null when the job was not created from another job.

created_at: str | None : Created at from the Greenhouse v3 jobs record.

custom_fields: dict[str, typing.Any] | None : Org-defined custom fields keyed by the field's name_key. Each value carries the field's display name, its type, and its value.

department_id: int | None : Id of the department this job is assigned to. null when no department is set.

id: int | None : Id from the Greenhouse v3 jobs record.

is_template: bool | None : If true, this job is a template used as the source for new jobs rather than a real requisition. Templates do not accept applications; reference them via template_job_id on POST /v3/jobs.

model_config : The type of the None singleton.

name: str | None : Internal job title shown to the hiring team in Greenhouse (e.g. Senior Backend Engineer). Distinct from the external-facing title on each job_post.

notes: str | None : Internal HTML notes about the job, surfaced to the hiring team in the Greenhouse UI. Not exposed on public job posts.

office_ids: list[typing.Any] | None : Ids of the offices this job is assigned to. A job can span multiple offices; empty array or null when no offices are set.

opened_at: str | None : Timestamp the job first transitioned to open, in ISO 8601. null while the job is still in draft.

requisition_id: str | None : Partner-supplied external identifier for the requisition (e.g. an HRIS or ATS code). Free-form string, not unique across the organization, and null when no external id has been set.

status: str | None : Lifecycle status of the job. draft while it is being scaffolded, open once it has at least one open opening, and closed after every opening is closed. A job moves to closed automatically when its last open opening is closed via PATCH /v3/openings/{id}.

updated_at: str | None : Updated at from the Greenhouse v3 jobs record.

OffersSearchData(**data: Any) : Search result data for offers entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

application_id: int | None : Id of the application this offer is extended on. Every offer belongs to exactly one application; the offer is voided if the application is rejected or deleted.

candidate_id: int | None : Id of the candidate (person) receiving this offer. Resolved through the offer's application.

created_at: str | None : Created at from the Greenhouse v3 offers record.

custom_fields: dict[str, typing.Any] | None : Org-defined custom fields keyed by the field's name_key. Each value carries the field's display name, its type, and its value.

id: int | None : Id from the Greenhouse v3 offers record.

job_id: int | None : Id of the job this offer's application is on.

model_config : The type of the None singleton.

opening_id: int | None : Id of the specific opening this offer is being extended for. null when the offer has not yet been linked to an opening.

resolved_at: str | None : Timestamp the offer was resolved (Accepted or Rejected), in ISO 8601. Date updates submitted through PATCH /v3/offers/{id} are normalized to noon UTC on the supplied date. null while the offer is still Created or has been superseded as Deprecated without a resolution.

sent_on: str | None : Date the offer was sent to the candidate, in ISO 8601 (YYYY-MM-DD). null until the offer has been sent.

starts_on: str | None : Candidate's proposed start date, in ISO 8601 (YYYY-MM-DD). null when no start date has been set on the offer.

status: str | None : Lifecycle status of the offer. Created for offers still being drafted or pending approval, Accepted once the candidate accepts, Rejected if declined or withdrawn, and Deprecated for superseded prior versions (a new offer version replaces an earlier one with this status).

updated_at: str | None : Updated at from the Greenhouse v3 offers record.

version: int | None : Revision number of this offer within its application. Greenhouse creates a new offer row (incrementing version) whenever a tracked field on an existing offer changes — typically starts_on, opening_id, or a custom field configured to trigger a new version. Pair with current_only=true to filter the list endpoint down to the latest version per application.

OfficesSearchData(**data: Any) : Search result data for offices entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

created_at: str | None : Created at from the Greenhouse v3 offices record.

external_id: str | None : Stable identifier supplied by the customer or HRIS for cross-system reconciliation. null when no external id has been set. Available when the org_structure_external_id product flag is enabled.

id: int | None : Id from the Greenhouse v3 offices record.

location: str | None : Free-form physical location string for the office (e.g. New York, NY, USA). null for offices that have no location set, including most remote offices.

model_config : The type of the None singleton.

name: str | None : Display name of the office (e.g. San Francisco, Remote (US)). Unique among active offices in the same organization.

parent_id: int | None : Id of the parent office when offices are organized hierarchically. null for top-level offices. References another /v3/offices row in the same organization.

primary_in_house_contact_user_id: int | None : Id of the Greenhouse user designated as the office's primary internal contact, typically the local recruiting lead. References a /v3/users row. null when no contact has been assigned.

updated_at: str | None : Updated at from the Greenhouse v3 offices record.

SourcesSearchData(**data: Any) : Search result data for sources entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

created_at: str | None : Created at from the Greenhouse v3 sources record.

id: int | None : Id from the Greenhouse v3 sources record.

model_config : The type of the None singleton.

name: str | None : Display name of the source as recruiters see it in Greenhouse (e.g. LinkedIn (Prospecting), Indeed, Referral, Internal Applicant, or a custom agency name). For organization-specific sources this is the label the org configured; for global Greenhouse sources it is the standard public name.

type_: dict[str, typing.Any] | None : The sourcing strategy this source rolls up to — the broader category used for reporting. Sources are grouped under sourcing strategies such as Agencies, Referral, Third-party boards, Prospecting, Social media, Company marketing, In person event, MyGreenhouse, and Other. Use the strategy when aggregating candidate volume by channel; use the source itself when reporting on a specific channel within that category.

updated_at: str | None : Updated at from the Greenhouse v3 sources record.

UsersSearchData(**data: Any) : Search result data for users entity.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors (in MRO)​

  • pydantic.main.BaseModel

Class variables​

agency_id: int | None : Id of the staffing agency this user belongs to, when the user is an external agency recruiter rather than an employee of your organization. null for in-house users.

created_at: str | None : Created at from the Greenhouse v3 users record.

custom_fields: dict[str, typing.Any] | None : Org-defined custom fields keyed by the field's name_key. Each value carries the field's display name, its type, and its value.

deactivated: bool | None : Whether the user has been deactivated. Deactivated users cannot sign in or be assigned to new jobs, but their historical activity (notes, scorecards, emails) is preserved. Toggle via POST /v3/users/{id}/deactivate and POST /v3/users/{id}/activate.

department_ids: list[typing.Any] | None : Ids of the departments this user is assigned to. Used to scope future job permissions and to filter the user list by department. Empty when the user is not pinned to any department.

emails: list[typing.Any] | None : All email addresses on the user's account, including the primary address and any additional verified addresses.

employee_id: str | None : Partner-supplied external employee identifier, typically the user's HRIS or payroll id. Free-form string; not unique across organizations and null when no employee id has been set.

first_name: str | None : First name from the Greenhouse v3 users record.

id: int | None : Id from the Greenhouse v3 users record.

interviewer_tags: list[typing.Any] | None : Interviewer tags applied to this user — the labeled skill or panel groupings (e.g. Senior Engineer, Bar Raiser) used to suggest qualified interviewers when building an interview plan. Each entry pairs the tag's id with its name.

job_title: str | None : Free-form job title set on the user's Greenhouse profile (e.g. Senior Recruiter). Not synchronized with any HRIS title.

last_name: str | None : Last name from the Greenhouse v3 users record.

linked_candidate_ids: list[typing.Any] | None : Ids of candidate records linked to this user. Populated when an employee is represented by both a user record (for Greenhouse access) and a candidate record (for past or internal applications).

model_config : The type of the None singleton.

name: str | None : Concatenation of first_name and last_name rendered as a single display string. Provided for convenience; partners that need either component should read first_name/last_name directly.

office_ids: list[typing.Any] | None : Ids of the offices this user is assigned to. Used to scope future job permissions and to filter the user list by office. Empty when the user is not pinned to any office.

primary_email: str | None : Primary email address on the user's account. Sign-in identifier and the address Greenhouse uses for outbound mail; additional verified addresses are not surfaced here. Service accounts (integration/ISU users) have no email and are excluded from this endpoint by default; when included via show_service_accounts=true, their primary_email is an empty string.

site_admin: bool | None : Whether the user holds the Site Admin role. Site admins have unrestricted access to every non-confidential job and to organization-level settings. Demote a site admin to a Basic user with POST /v3/users/{id}/revoke_permissions.

updated_at: str | None : Updated at from the Greenhouse v3 users record.

Was this page helpful?