Loxo

HOW in lib/loxo.py.

Auth & config (agency-scoped)

• Base URL: https://app.loxo.co/api/{LOXO_AGENCY_SLUG} — Loxo is agency-scoped. The host is fixed; an agency subdomain 404s.
• Env: LOXO_API_KEY (Bearer), LOXO_AGENCY_SLUG (bare slug, e.g. acme — a pasted URL/domain is reduced to its first label). Never hardcode.
• Paths CONFIRMED from loxo.readme.io (2026-06-01). Jobs paginate via page/per_page; people and companies paginate via scroll_id (+ a Lucene query). Index: reference/docs/loxo/raw/endpoints.md.

Operations

Jobs: list_jobs, get_job, create_job, update_job. People: list_people, get_person, create_person, update_person. Activity log (notes, replies, calls): list_activity_types, create_person_event. Companies (accounts): list_companies, iter_companies, get_company, create_company, update_company, plus list_dynamic_fields + company_custom_fields for the agency's custom fields. Job↔candidate: list_job_candidates (GET /jobs/{id}/candidates), apply_to_job (POST /jobs/{id}/apply).

Notes & guardrail

• Adding a candidate to a job is apply_to_job (POST /jobs/{job_id}/apply) — multipart/form-data with REQUIRED email+name+phone (+ optional resume file). create_job_candidate is a deprecated alias.
• Notes and replies go in as person events. Find the note or reply type in list_activity_types and take its numeric id, then call create_person_event with that activity_type_id (required), person_id and notes. With job_id, use a note-type activity: a pipeline-stage type moves the candidate on that job.
• Production ATS writes — pilot one, confirm, then bulk.
• list_companies paginates by cursor only: pass the scroll_id each response returns, with a per_page up to 100 — there is no page param. iter_companies(max_records=…) walks the whole account list.
• A company's agency custom fields arrive as custom_hierarchy_1..6 {id, value} pairs, and each slot holds a different field per agency. Read the definitions once with list_dynamic_fields, then pass a {"custom_hierarchy_3": "Therapeutic area"} map to company_custom_fields(company, labels).

Handoff

ATS write target: enriched candidates → create_person / apply_to_job (assign to a job); reply notes → create_person_event. Company-first BD: iter_companies → each account's url (website) → hyreflow_native career-page scraping for their open roles → contacts via the people_search waterfall.

Callable surface — lib/loxo.py

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

• apply_to_job(job_id: str, *, email: str, name: str, phone: str, resume: tuple | None = None, **fields) -> Any — POST /jobs/{job_id}/apply — add a candidate to a job. CONFIRMED.
• 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_person(id, payload). Destructive methods (delete) are refused. See lib/_base.run_ops.
• company_custom_fields(company: dict, labels: dict | None = None) -> dict — Local (no HTTP): a company's custom_hierarchy_1..6 slots as {field_name: value}.
• create_companies_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — POST /companies for many records, rate-limited.
• create_company(payload: dict) -> Any — POST /companies — create a company (form-encoded, company[...] params). CONFIRMED.
• create_job(payload: dict) -> Any — POST /jobs — create a job (form-encoded, job[...] params). CONFIRMED.
• create_job_candidate(job_id: str, payload: dict) -> Any — DEPRECATED alias → apply_to_job (POST /jobs/{id}/apply, multipart).
• create_jobs_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — POST /jobs for many records, rate-limited.
• create_people_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — POST /people for many records, respecting LOXO_RATE_LIMIT_RPM.
• create_person(payload: dict, *, resume: tuple | None = None, document: tuple | None = None) -> Any — POST /people — create a person (multipart, person[...] params). CONFIRMED.
• create_person_event(payload: dict) -> Any — POST /person_events — log an activity (note, call, email, reply) on a person (form-encoded, person_event[...] params). CONFIRMED.
  • requires: activity_type_id
  • example: {"activity_type_id":71536,"person_id":123456,"notes":"Replied to outreach: open to a call next week."}
• get_company(company_id: str) -> Any — GET /companies/{id} — one company, with its website (url) and custom fields. CONFIRMED.
• get_job(job_id: str) -> Any — GET /jobs/{id}. CONFIRMED.
• get_person(person_id: str) -> Any — GET /people/{id}. CONFIRMED.
• iter_companies(*, per_page: int = 100, max_records: int = 1000, cursor: str | None = None, **params) -> _base.PagedResult — GET /companies — follow the scroll cursor until the account list is exhausted. CONFIRMED.
• list_activity_types(**params) -> Any — GET /activity_types — the agency's activity types (call, email, note, …); their ids feed create_person_event. Optional workflow_id filter. CONFIRMED.
• list_companies(**params) -> Any — GET /companies — search/list companies (accounts, employers). CONFIRMED.
• list_dynamic_fields() -> Any — GET /dynamic_fields — the agency's custom (dynamic) field definitions. CONFIRMED.
• list_job_candidates(job_id: str, **params) -> Any — GET /jobs/{job_id}/candidates — candidates on a job, with pipeline stage. CONFIRMED.
• list_jobs(**params) -> Any — GET /jobs — paginated (page, per_page). CONFIRMED.
• list_people(**params) -> Any — GET /people — paginated people/candidates (scroll_id/per_page/query). CONFIRMED.
• update_company(company_id: str, payload: dict) -> Any — PUT /companies/{id} (form-encoded, company[...] params). CONFIRMED.
• update_job(job_id: str, payload: dict) -> Any — PUT /jobs/{id} (form-encoded, job[...] params). CONFIRMED.
• update_person(person_id: str, payload: dict) -> Any — PUT /people/{id} (form-encoded, person[...] params). CONFIRMED.