Skip to main content

Comeet

Comeet (now Spark Hire Recruit) is an applicant tracking system (ATS) and collaborative hiring platform. The Willow connector targets the Recruiting API so an MCP host can read and manage candidates, leads, positions, openings, questionnaires, files, and audit logs without screen-scraping the Recruit UI.

Authentication​

Comeet's Recruiting API does not accept a raw API key as a bearer token. Every request must carry a JWT that you sign yourself (authorization docs) from two values:

  • api-key — obtained by a Recruit customer from Settings → Integrations when the integration is activated.
  • secret — issued to an approved Comeet integration partner (see the Integration Partners guide).

The token is a JWT signed with HS256 whose payload is { "iss": <api-key>, "exp": <expiry> }. Willow sends it as Authorization: Bearer <token>.

You provide the signed token

This connector uses a pre-signed JWT as the credential. You generate the token yourself and paste it into Willow. Because Comeet's own examples use a short (10-minute) expiry, set a long-lived exp if you want a standing integration — and be aware Comeet may reject tokens whose expiry is too far in the future, in which case you'll need to refresh the pasted token periodically.

Generate the token​

# pip install pyjwt
import jwt, time

token = jwt.encode(
    {"iss": "YOUR_API_KEY", "exp": time.time() + 315360000},  # ~10 years
    "YOUR_API_SECRET",
    algorithm="HS256",
)
print(token)

Configure in Willow​

  1. In Willow, go to Integrations → New → Built-in.
  2. Select Comeet and click Use.
  3. Under Authentication Type, choose API Key.
  4. Paste the signed JWT from the step above into the credential field and Save Changes.
  5. Run List Positions with no arguments to verify. A successful 200 confirms the token, api-key, and secret are all valid.

Available Tools​

The Comeet connector ships 17 tools across the recruiting lifecycle.

Candidates (8 tools)​

  • List Candidates — filter by status, creation/status-change/activity time windows, person last-activity, and deleted state.
  • Retrieve Candidate — fetch a single candidate by UID (or by Recruit URL ID with use_real_id), with optional include fields.
  • Create Candidate — create a candidate for a position, with optional resume, files, links, picture, source contact, address, custom fields, and note.
  • Retrieve Candidate Files — list a candidate's files with temporary (~15 min) download URLs.
  • Add File to Candidate — upload a Base64-encoded file to a candidate (max 6MB).
  • Add Resume to Candidate — upload a Base64-encoded resume (.pdf, .doc, .docx).
  • Find Duplicate Candidates and Leads — check for existing candidates/leads by email, phone, LinkedIn, or name.
  • List Deleted Candidates or Leads — retrieve UIDs of deleted/pseudonymized records so you can purge them from your own system.

Leads (3 tools)​

  • List Leads — filter by outreach status and first-contact time windows.
  • Retrieve Lead — fetch a single lead by UID (or Recruit URL ID with use_real_id).
  • Create Lead — create a sourced/passive lead for a position.

Positions (4 tools)​

  • List Positions — filter by status, publication/discreet/template flags, employee-only visibility, and last-updated time.
  • Create Position — create a position (and optional openings) with hiring team, location, salary range, categories, and details.
  • Clone Position — clone a template position (is_template = true) into a new position.
  • Update Position — patch an existing position's properties.

Questionnaires (1 tool)​

  • List Questionnaires — list the company's questionnaires with their questions and options.

Audit Logs (1 tool)​

  • List Audit Logs — retrieve access/security events (Beta) in SIEM CIM format; filter by time, event types, and actions. Retained for 30 days.

Permissions​

The access an integration has is defined by the permissions attached to your partner secret by Comeet — an admin approves them when activating the integration and cannot narrow them per token. Grant only what your integration needs (e.g. Candidates: Create a new candidate, Positions: Update a position, Audit logs: Retrieve logged events). Missing permissions surface as authorization errors on the affected tools.

Pagination​

List endpoints that can return many results (List Candidates, List Leads, List Positions, List Questionnaires) include a next_page field in the response — a full URL to the next page — or null when there are no more results.

Troubleshooting​

401 Unauthorized on every call​

Cause: The pasted JWT has expired, or the api-key/secret used to sign it is wrong.

Solution: Regenerate the token with a valid api-key and secret and a far-future exp, then update the credential in Willow. Confirm the api-key is the one shown in Settings → Integrations for your account.

401 duplicate_candidate / duplicate_lead on retrieve​

Cause: The record was removed because it was merged as a duplicate of another candidate/lead.

Solution: Use Find Duplicate Candidates and Leads to locate the surviving record and query that UID instead.

409 Conflict on create​

Cause: A candidate/lead with the same partner_candidate_id/partner_lead_id already exists in that position with a status in progress. The response includes the existing candidate_uid/lead_uid.

Solution: Reuse the existing record rather than creating a duplicate.

Additional Resources​

On this page