Coding agent documentation index Fetch the complete documentation index at: https://docs.worklittle.com/docs-agent-manifest.json Use this file to discover all available pages before exploring further.

Manage candidates

Operate your employer ATS: candidates, pipeline stages, notes, interviews, employees, email, and offers.

Overview

The ATS routes list your organization's applicants and move them through your hiring pipeline.

# List candidates in a stage
curl -s "https://api.worklittle.com/candidates?limit=25&stage_key=applied" \
  -H "Authorization: Bearer $WORKLITTLE_API_KEY"

# Move one to another stage
curl -s -X PATCH "https://api.worklittle.com/candidates" \
  -H "Authorization: Bearer $WORKLITTLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidate_job_id":"CANDIDATE_JOB_ID","stage_key":"phone_screening","stage_label":"Phone screening"}'

Stage moves go through PATCH /candidates with the candidate's candidate_job_id, plus both stage_key and stage_label. Read valid stages from pipeline_stages in the list response or from GET /pipeline-stages. The defaults are sourced, applied, rejected, phone_screening, technical_interview, team_match, offer, denied, employee, offboarding, and alumni. Moving a candidate to employee creates the employee record. To edit profile fields instead, send candidate_id (or ids) and the fields to change.

These routes are scoped to your organization and never appear in public job search. Use a session or a Bearer key with jobs:applications. A jobs:read key is not enough. MCP: list_candidates, get_candidate, update_candidate. SDK and CLI: Libraries.

Areas

| Area | REST prefix | MCP examples |
| --- | --- | --- |
| Candidates | `/candidates`, `/candidate-*` | `list_candidates`, `get_candidate` |
| Employees | `/employees` | `list_employees`, `add_employee` |
| Email and offers | `/email-messages`, `/email/send`, `/email/sends`, `/offers` | `send_email`, `list_sent_emails`, `create_offer` |
| Applications (read) | `/business/jobs/:id/applications` | `list_job_applications`, `get_job_application` |

Applying to catalog jobs is a different API: Apply for jobs. Hosted submit_job_application is covered in Embedded job board. Applying creates an application. The ATS creates a candidate record once the application is linked to your organization.

Candidates (REST)

| Endpoint | Methods | Purpose |
| --- | --- | --- |
| `/field-hints` | GET | Placeholder examples for contact and employment fields |
| `/candidates` | GET, PATCH | List (paginated with `limit`) or update core fields and stage |
| `/candidates/:id` | GET | Full profile, applications, notes, interviews, `field_hints` |
| `/candidates/:id/resume-file` | GET, POST | Download the resume, or upload one when the applicant has none (body `{ file: { filename, content_base64, mime? } }`) |
| `/candidates/:id/files` | POST | Attach any file to the candidate (same `file` body, max 10 MB) |
| `/candidates/:id/files/:fileId` | GET, DELETE | Download (`?view=1` inline) or delete an attached file |
| `/candidates/:id/bookmark` | POST, DELETE | Org-wide bookmark |
| `/candidates/:id/alerts` | GET, PATCH | Your pipeline alerts and follow-up reminder |
| `/candidates/:id/generate-about-summary` | POST | Regenerate one-sentence `about_summary` |
| `/candidate-alerts` | GET | All of your candidate alert settings |
| `/candidates/import` | POST | Bulk import candidates |
| `/candidates/merge` | POST | Merge two candidates into one profile. Body `{ ids: [a, b], preview?: true, remove_user_id? }`; `preview` returns who is kept and the merged name without changing anything |
| `/business/candidates/answers` | POST | Fetch application Q&A for many candidate ids |
| `/job-applications/:id/cover-letter-file` | GET | Download cover letter file for an application |
| `/candidate-notes` | GET, POST, PATCH, DELETE | Notes (`?candidate_id=` on GET). `metadata.resume_pin` `{ x, y }` (0–1 of the resume width and height) places a floating note on the resume; reads return it as `resume_pin` |
| `/candidate-notes/:id` | GET, DELETE | Single note with attachments |
| `/candidate-note-attachments` | POST, DELETE | Upload attachment (base64 or raw bytes) |
| `/candidate-note-attachments/:id` | GET | Download attachment |
| `/candidate-experience` | POST, PATCH, DELETE | Work history CRUD |
| `/candidate-education` | POST, PATCH, DELETE | Education CRUD |
| `/candidate-interviews` | POST, PATCH, DELETE | Interview CRUD |
| `/interview-answers` | POST, PATCH, DELETE | Interview Q&A CRUD |
| `/pipeline-stages` | GET | Pipeline stages for your organization |

List filters: limit, cursor, sort, q, location, stage_key, posted_job_id, bookmarked=true. Lists are paginated. Pass limit and follow cursor.

Download a resume with GET /candidates/:id/resume-file. This is not the People resume unlock.

POST /candidates/:id/resume-file stores a resume on your organization's candidate record. The applicant's own Worklittle resume still wins when they have one, and is never overwritten. Attached files (POST /candidates/:id/files) are listed in files on GET /candidates/:id.

Employees (REST)

| Endpoint | Methods | Purpose |
| --- | --- | --- |
| `/employees` | GET, POST | List or create employees |
| `/employees/:id` | GET, PATCH, DELETE | Employee detail, update, or remove |
| `/employees/merge` | POST | Merge two employees (and their linked candidates). When both are org members, `preview` returns `requires_member_choice` + `members`; commit with `remove_user_id` to remove that person from the org |
| `/employee-employment-periods` | POST, PATCH, DELETE | Employment stint history |
| `/employee-performance-feedback` | PUT, DELETE | Performance feedback rows |

Email and offers

| Endpoint | Methods | Purpose |
| --- | --- | --- |
| `/email-messages` | GET, POST, PUT, PATCH, DELETE | Stage email templates and settings |
| `/email-messages/preview` | POST | Preview a template before send |
| `/email/send` | POST | Send or schedule ATS email to candidates |
| `/email/sends` | GET | List org sent emails + open stats (ATS + automation) |
| `/usage` | GET | Org usage / audit logs (`organization_logs`; same Destination as Business Usage — `where_label` / `where_href` for Chat, Voice, jobs, Private, …; metered AI + free burns + org activity; filters: `source` incl. `org_activity` / `platform_ai`, `since`, `cursor`, `api_key_id`; `ledger_type`) |
| `/offers` | GET, POST, PATCH, DELETE | Offer list and CRUD |

Template CRUD and preview are free. Each successful send is metered - see Pricing.

Events

Subscribe to candidate.application_submitted, candidate.stage_changed, offer.created, and more in Webhooks.