Spott

Use Spott to load enriched leads and candidates into the ATS and to read/write jobs, clients, contacts, applications, notes, placements, tasks, and opportunities. It is a sink for an enriched CSV produced by the sourcing/enrichment layer, alongside the other CRM/ATS integrations.

**Free on hyreflow (0 credits)** — runs on your own connected Spott account.

Capabilities

Tool	Does	Cost
search_candidates	Query candidates	Free
create_candidate	Create a candidate (req. firstName, lastName)	Free
search_clients	Query clients (companies-as-accounts)	Free
create_client	Create a client (req. name, description, size, specialties)	Free
create_client_contact	Create a client contact under a client (req. firstName, lastName)	Free
search_jobs	Query jobs	Free
create_job	Create a job (req. stageId + company/role fields)	Free
create_application	Create an application (req. vacancyId, candidateId, stageId, statusId)	Free
move_application	Move an application to another stage	Free
get_vacancy_stages	Pipeline stage IDs for jobs	Free
get_client_stages	Pipeline stage IDs for clients	Free
get_opportunity_stages	Pipeline stage IDs for opportunities	Free
create_opportunity	Create an opportunity (req. stageId)	Free
search_people	Tenant-wide people search	Free
list_lists	Browse lists (candidate/client/client-contact, personal or workspace)	Free
find_list	Resolve a list by name	Free
create_list	Create a list for candidates, clients, or client contacts	Free
add_to_list_by_name	Resolve a list by name and link records to it	Free
remove_from_list_by_name	Resolve a list by name and unlink records from it	Free
link_candidates_to_list	Link candidates to a list by id	Free
unlink_candidates_from_list	Unlink candidates from a list by id	Free

Guidance

• The module name is spott; run it via hyreflow tools execute spott <method>.
• Writes are real production changes — dry-run one record, show the payload + response, get explicit go-ahead before bulk.
• Jobs, applications, and opportunities all need a pipeline stageId (applications also need statusId) — resolve it first with get_vacancy_stages, get_client_stages, or get_opportunity_stages.
• Record deletion is not exposed for any resource.
• List name resolution is exact-but-case-insensitive; an ambiguous name (more than one list sharing it) fails rather than guessing which list was meant.
• Linking or unlinking records to a list is capped at 250 ids per call — an over-limit or duplicate id list is rejected, not trimmed.
• add_to_list_by_name won't create a missing list, and removing records from a list does not delete the records.
• Handoff: enrichment produces a CSV → inspect it (rows, columns, samples) → map columns → load via the create_* methods.

hyreflow tools execute spott create_candidate \
  --payload '{"firstName":"Ada","lastName":"Lovelace","email":"[email protected]"}'

hyreflow tools execute spott add_to_list_by_name \
  --payload '{"list_name":"Acme Q4 shortlist","record_ids":["candidate-123","candidate-456"]}'

Rate limits & bulk writes

Spott publishes a rate limit of 600 requests/minute per API key. Use the batch helpers for large pushes — they loop single calls and pace requests automatically:

hyreflow tools execute spott create_candidates_batch \
  --payload '{"payloads":[{"firstName":"Ada","lastName":"Lovelace"},{"firstName":"Grace","lastName":"Hopper"}]}'

Spott is an ATS sink, not a waterfall member — wire it as the final push after source → enrich → verify.