Crelate

HOW in lib/crelate.py.

Auth & config (API key)

• Endpoint: Crelate's REST API v3 (https://app.crelate.com/api3); every response is an envelope of Data, Metadata and Errors.
• Auth: an X-Api-Key header. The key comes from the user's own Crelate profile (Your Profile & Preferences → API Access → Enable API Access) and acts as that user. Non-admins need an admin to allow API Access on their role; API access is on Crelate's Business plan and higher. Regenerating or disabling the key in Crelate breaks the connection.
• BYOK: api_key = the Crelate API key, no extra fields. A connected workspace never reads env.
• ping() = safe read-only pilot (the user the key belongs to).

Noun mapping

Contact = any person: a candidate and/or a client contact, told apart by RecordType. Company = account. Job = role. Workflow status = a pipeline stage a contact can sit at on a job.

Operations

Contacts: list_contacts, search_contacts, get_contact, create_contact, update_contact, create_contacts_batch. Jobs: list_jobs, search_jobs, get_job, list_workflow_statuses, add_contact_to_job. Companies / notes: list_companies, search_companies, get_company, list_notes, create_note.

• Paging: list_* take offset + limit, limit at most 200; search_* take limit at most 100. A larger value is rejected, not clamped. Keep raising offset while Metadata.MoreRecords is true.
• Search returns summary fields only; use get_* for the full record.
• Hyreflow paces all Crelate calls at 100 requests/minute (Crelate limits by caller IP, about 120/min).
• A create that matches the workspace's duplicate rules returns 409. No delete operation is exposed for any record.

Guardrail

Production ATS writes — pilot one record, confirm, then bulk. Check list_contacts with emails before a create. Required fields are configured per Crelate account.

Handoff

ATS write target: enriched candidates → create_contact → add_contact_to_job.

Callable surface

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

• add_contact_to_job(job_id: str, contact_id: str, *, status_name: str | None = None, status_id: str | None = None) -> Any — POST /jobs/{jobId}/contact/{contactId} — put a contact on a job's pipeline at a stage, named by exactly one of status_name or status_id (see list_workflow_statuses).
• 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_contact(id, payload). Destructive methods (delete) are refused. See lib/_base.run_ops.
• create_contact(payload: dict) -> Any — POST /contacts — create a contact; Data is the new id. Body is the record itself (FirstName, LastName, RecordType, EmailAddresses_Work: {Value, IsPrimary}, Websites_LinkedIn: {Value}, ...); the adapter wraps it as {"entity": ...}. A 409 means the workspace's duplicate rules matched.
• create_contacts_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict — POST /contacts for many records, one at a time, respecting the Crelate rate limit.
• create_note(payload: dict) -> Any — POST /notes — add a note. Body {Display: text, ParentId: {Id, EntityName: "Contacts"}, RegardingId?: {Id: job id}, When?}; the adapter wraps it as {"entity": ...}.
• get_company(company_id: str) -> Any — GET /companies/{id} — read one company.
• get_contact(contact_id: str) -> Any — GET /contacts/{id} — read one contact.
• get_job(job_id: str) -> Any — GET /jobs/{id} — read one job.
• list_companies(*, offset: int = 0, limit: int = 50, **filters) -> Any — GET /companies — one page (limit <= 200). Filters: names, emails, ids, parent_ids, record_types, modified_after, sort_by, fields.
• list_contacts(*, offset: int = 0, limit: int = 50, **filters) -> Any — GET /contacts — one page (limit <= 200). Filters (lists repeat the param): ids, emails, phone_numbers, external_primary_keys, job_ids, record_types, statuses, tag_names, owner_ids, modified_after, created_after, cities, states, zip_codes, sort_by (e.g. "CreatedOn asc"), fields ("FirstName,LastName").
• list_jobs(*, offset: int = 0, limit: int = 50, **filters) -> Any — GET /jobs — one page (limit <= 200). Filters: name, ids, company_ids, candidate_ids, owner_ids, statuses, published, job_codes, job_numbers, opened_after, closed_after, modified_after, sort_by, fields.
• list_notes(*, offset: int = 0, limit: int = 50, **filters) -> Any — GET /notes — one page (limit <= 200).
• list_workflow_statuses(*, offset: int = 0, limit: int = 50, **filters) -> Any — GET /workflowstatuses — the pipeline stages a contact can sit at on a job.
• ping() -> Any — GET /users/self — the user the API key belongs to (free read; used to test a connection).
• search_companies(query: str, *, limit: int = 10) -> Any — GET /companies/search — keyword search (limit <= 100).
• search_contacts(query: str, *, limit: int = 10) -> Any — GET /contacts/search — keyword search (limit <= 100); returns summary fields only.
• search_jobs(query: str, *, limit: int = 10) -> Any — GET /jobs/search — keyword search (limit <= 100).
• update_contact(contact_id: str, payload: dict) -> Any — PATCH /contacts/{id} — partial update; only the fields sent change (Tags is replaced whole).