Bullhorn

HOW in lib/bullhorn.py. Docs: bullhorn.github.io/rest-api-docs.

Auth — 3-leg flow (most complex adapter; handled in _login)

0. GET rest.bullhornstaffing.com/rest-services/loginInfo?username=… → oauthUrl + restUrl for the user's datacenter (e.g. auth-emea / rest-emea). Tenants are cluster-pinned: the global auth host answers a cross-cluster login with its login page, not a code.
1. GET {oauthUrl}/authorize (client_id + username/password + action=Login) → 302 with ?code=.
2. POST {oauthUrl}/token (grant_type=authorization_code) → access_token.
3. POST {restUrl}/login?version=*&access_token=… → BhRestToken + restUrl. Then every call hits {restUrl}<path> with BhRestToken. The client re-logs in once on 401.

• Env: BULLHORN_CLIENT_ID, BULLHORN_CLIENT_SECRET, BULLHORN_USERNAME, BULLHORN_PASSWORD; optional BULLHORN_REDIRECT_URI — leave unset so Bullhorn uses the OAuth app's registered URI (a mismatch fails authorize with "Invalid Redirect URI"). Never hardcode. BYOK: api_key = client ID; client_secret, username, password are the extra fields.
• ping() = safe read-only pilot.

Operations (CONFIRMED from bullhorn.github.io/rest-api-docs, 2026-06-01)

search(entity, query, fields) — GET /search/{Entity} Lucene (indexed: Candidate, JobOrder, ClientContact, ClientCorporation…). query(entity, where, fields) — GET /query/{Entity} SQL-style (non-indexed). get_entity (GET /entity/{Entity}/{id}), create_entity (PUT /entity/{Entity}), update_entity (POST /entity/{Entity}/{id}). request() covers the rest. BhRestToken via query param is valid (also accepted as a header). All path patterns verified.

Guardrail

Production ATS writes — pilot one record, confirm, then bulk.

Handoff

ATS write target: enriched candidates → create_entity("Candidate", …).

Callable surface — lib/bullhorn.py

Import: from lib.bullhorn import Bullhorn → instantiate Bullhorn() (reads key from env). Generic passthrough: request(method, path, *, params, json).

• batch(method: str, calls: list, *, stop_on_error: bool = False) -> dict — Batched get/search/update/create: run one method over many inputs, rate-limited. Each call is a value -> method(value), or {"args": [...], "kwargs": {...}} for multi-arg methods like update_entity(entity, id, payload). Destructive methods (delete) are refused. See lib/_base.run_ops.
• create_candidate(payload: dict) -> Any — PUT /entity/Candidate — create a candidate.
• create_candidates_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — Create many candidates sequentially while respecting the 1,500 req/min limit.
• create_client_contact(payload: dict) -> Any — PUT /entity/ClientContact — create a contact.
• create_client_contacts_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — Create many client contacts sequentially, rate-limited.
• create_client_corporation(payload: dict) -> Any — PUT /entity/ClientCorporation — create a company.
• create_client_corporations_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — Create many companies sequentially, rate-limited.
• create_entity(entity: str, payload: dict) -> Any — PUT /entity/{entity} — create a record.
• create_job_order(payload: dict) -> Any — PUT /entity/JobOrder — create a job.
• create_job_orders_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — Create many job orders sequentially, rate-limited.
• get_entity(entity: str, entity_id: int, *, fields: str = '*') -> Any — GET /entity/{entity}/{id}?fields=...
• ping() -> Any — GET ping — verify session (safe read-only pilot).
• query(entity: str, where: str, *, fields: str = '*', **params) -> Any — GET /query/{entity}?where=...&fields=... — SQL-style where (non-indexed entities).
• search(entity: str, query: str, *, fields: str = '*', **params) -> Any — GET /search/{entity}?query=...&fields=... — Lucene-style search (indexed entities).
• update_entity(entity: str, entity_id: int, payload: dict) -> Any — POST /entity/{entity}/{id} — update a record.