Spott

Use Spott as an ATS/CRM write target: push sourced + enriched candidates and leads, sync clients (companies-as-accounts) and their contacts, and move applications through a job's pipeline. Spott also exposes notes, tasks, placements, opportunities, and a tenant-wide people search.

Capabilities

Guidance

• Auth is an x-api-key header, generated in Spott under Settings → API (admin permissions required; the key is shown once). The owner's key is the workspace key, and each member adds their own, see Personal keys.
• Production ATS writes: dry-run one record, show payload + response, confirm before bulk.
• Creating a job needs a pipeline stageId, and creating an application needs stageId + statusId, resolve them first with get_vacancy_stages, get_client_stages, or get_opportunity_stages before writing.
• 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: sourced + enriched candidates/leads → create_candidate → create_application → review in Spott.

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"]}'

Personal keys

Spott credits every note and list to whoever owns the key that made the change, so every member adds their own Spott key and their work shows up under their name. Members don't share the workspace key: until a member adds their own, Spott won't run for them. The workspace owner uses the workspace key. In Spott the key is under Settings → API (you need admin permissions in Spott). See Personal keys.

Rate limits & bulk writes

Spott publishes a rate limit of 600 requests/minute per API key, the adapter paces to that number rather than guessing a conservative default. Most list endpoints use cursor pagination; placements use offset pagination instead. Use create_candidates_batch, create_clients_batch, and create_notes_batch for large single-record pushes, or the native bulk endpoints for applications, batch helpers pace automatically. See Bulk pushes to ATS / recruiting CRM.

Pagination

list_* methods walk every page automatically — limit is the vendor page size (max 50), not a total count. Two knobs bound a pull:

• max_items caps the total records returned. When more data exists upstream the call returns truncated: true in _meta.pagination along with an opaque next_cursor token — pass it back as cursor on the same call (with the same filters) to continue where it left off. next_cursor also appears when the engine's own 500-item result cap cuts a pull short.
• modified_since/modified_until bound the result set by record timestamps for incremental syncs.

Raw vendor cursors are still accepted on list_applications and list_opportunities for back-compat. Resume tokens are bound to the call's filter set — changing filters between calls rejects the token rather than silently resuming a different walk.