Carerix

HOW in lib/carerix.py.

Auth & config (client credentials)

• Endpoint: one GraphQL endpoint, https://api.carerix.io/graphql/v1/graphql; every call is a fixed, typed document.
• Auth: OAuth 2.0 client credentials from a Carerix confidential client. The token URL is built from the tenant name read off the pasted Carerix URL (e.g. https://acme.carerix.net → acme); the pasted URL is never fetched. Tenants on a non-default identity host are not supported yet. The token is cached until shortly before it expires; an HTTP 401 triggers one fresh-token retry (also after a GraphQL UNAUTHENTICATED on the top-level field, which means nothing ran).
• BYOK: api_key = Client ID; client_secret and tenant are the extra fields. Permissions are controlled in Carerix, on the client. A connected workspace never reads env.
• ping() = safe read-only pilot.

Noun mapping

Candidate = CREmployee, Vacancy = CRVacancy, Company = CRCompany, Contact = person at a company, Match = candidate-to-vacancy link carrying the pipeline status, Note = a to-do of kind note.

Operations

Candidates: list_candidates, search_candidates, get_candidate, create_candidate, create_candidates_batch. Vacancies / companies / contacts: list_vacancies, get_vacancy, list_companies, get_company, list_contacts, get_contact. Matches / notes: list_matches, get_match, update_match, list_notes, get_note, create_note.

• Filters are Carerix qualifier strings — list_*/search_candidates take qualifier. One page per call: page from 0, page_size max 100, rejected above that, not clamped.
• A GraphQL errors[] array or a missing result raises even on HTTP 200.
• Rate limit 10 req/s = 600/min, paced per client + tenant. Reads retry 429/5xx with backoff; writes are not retried after a timeout or server error (only after a 429 or an authentication refusal (HTTP 401, or GraphQL UNAUTHENTICATED on the top-level field), which Carerix rejects before they run).
• No delete operation is exposed for any record.

Guardrail

Production ATS writes — pilot one record, confirm, then bulk. Carerix documents no idempotency key for creates, so never blind-retry one. Required fields, the duplicate-detection key and status ids are tenant-specific.

Handoff

ATS write target: enriched candidates → create_candidate.

Callable surface

Call via the CLI: hyreflow tools execute carerix <method> --payload '{...}' (preview with --dry-run; hyreflow tools get carerix <method> returns the live contract + cost). Base: https://api.carerix.io/graphql/v1/graphql. Only the methods listed below are callable.

• batch(method: str, calls: list, *, stop_on_error: bool = False) -> dict — Batched get/update/create: run one method over many inputs, rate-limited.
• create_candidate(payload: dict, *, dedupe: bool = True) -> dict — POST /graphql/v1/graphql — crEmployeeCreate: create a candidate (CREmployeeRequest, e.g. {"firstName", "lastName", "emailAddress"}).
• create_candidates_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — POST /graphql/v1/graphql — crEmployeeCreate: create many candidates sequentially and rate-limited, each with Carerix's duplicate detection on (its match key is tenant-specific: search first).
• create_note(payload: dict) -> dict — POST /graphql/v1/graphql — crToDoCreate: add a note to a candidate, vacancy, match, company or contact.
• get_candidate(candidate_id: str) -> dict — POST /graphql/v1/graphql — crEmployee: one candidate by id.
• get_company(company_id: str) -> dict — POST /graphql/v1/graphql — crCompany: one company by id.
• get_contact(contact_id: str) -> dict — POST /graphql/v1/graphql — crContact: one contact by id.
• get_match(match_id: str) -> dict — POST /graphql/v1/graphql — crMatch: one match by id.
• get_note(note_id: str) -> dict — POST /graphql/v1/graphql — crNote: one note by id.
• get_vacancy(vacancy_id: str) -> dict — POST /graphql/v1/graphql — crVacancy: one vacancy by id.
• list_candidates(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crEmployeePage: one page of candidates (CREmployee), oldest first. qualifier is Carerix's filter string.
• list_companies(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crCompanyPage: one page of client companies (CRCompany), oldest first.
• list_contacts(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crContactPage: one page of client contacts (CRUser), oldest first.
• list_matches(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crMatchPage: one page of matches (CRMatch), the candidate-to-vacancy links that carry the pipeline status.
• list_notes(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crNotePage: one page of notes (a note is a CRToDo), oldest first.
• list_vacancies(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crVacancyPage: one page of vacancies (CRVacancy), oldest first.
• ping() -> dict — POST /graphql/v1/graphql — crEmployeePage: free read, one row count. Verifies the credentials, tenant and candidate read access (the BYOK probe).
• search_candidates(qualifier: str, page: int = 0, page_size: int = 100) -> list[dict] — POST /graphql/v1/graphql — crEmployeePage: one page of candidates matching a required qualifier, e.g. emailAddress = '[email protected]'.
• update_match(match_id: str, payload: dict) -> dict — POST /graphql/v1/graphql — crMatchUpdate: update a match's notes or move its pipeline status.