add_comment
ChatGPTAdd a comment to a candidate. Use this tool with candidate IDs obtained from get_candidates tool.
Business & Operations
Overview
Workable MCP Server helps users work with their Workable account from ChatGPT: discover accounts, inspect jobs and candidates, manage candidate workflow actions, handle employee lookup, time off, time tracking, requisitions, offers, departments, and performance review templates.
Tools
add_review
ChatGPTAdd a review/rating to a candidate. If you are looking for
add_candidate_rating, use add_review. Use this tool with candidate IDs obtained from get_candidates tool.approve_offer
ChatGPTApprove an offer by its ID
approve_requisition
ChatGPTApprove a requisition by its code, as the caller. Only works on a requisition that is pending and awaiting the caller's approval; any other requisition (already approved or rejected, or waiting on another approver) is reported as not awaiting approval.
bulk_create_time_entries
ChatGPTCreate complete time entries (clock-in + clock-out) for multiple employees in a single request (max 500)
clock_in
ChatGPTOpen a clock-in for an employee
clock_out
ChatGPTClose the currently open clock-in for an employee. Returns an array of entries closed by this clock-out
copy_candidate
ChatGPTCopy a candidate to a different job, leaving the original candidate in place. The candidate is added to the target job at the specified stage (or the default starting stage if not provided). Use this tool with candidate IDs obtained from get_candidates tools.
create_candidate
ChatGPTCreate a new sourced candidate and attach them to a specific job identified by its shortcode. The shortcode is required — use get_jobs to find the job shortcode if unknown. At minimum provide email plus either name or firstname+lastname.
create_department
ChatGPTCreate a new department.
create_requisition
ChatGPTCreate a new requisition. The response is the stored requisition: use its
code and id for follow-up calls, since the account may assign its own code and adjust the plan date. Depending on the approval workflow, the new requisition may be approved immediately (e.g. when the caller is its only approver).create_review_cycle_template
ChatGPTCreate a new performance review cycle template with sections and questions. All body fields (template title, section body, question body) must be non-empty strings — the API rejects empty values, so use a label like "Section rating" / "Overall rating" for rating questions rather than an empty string. Valid question types: "paragraph" (long text), "star_rated" (1-5 stars), "custom_rated" (labeled scale via metadata.ratingOptions), "numeric_rated" (numeric score), "multiple_choice" (options via metadata.answerOptions.choices). To mark a question as the section-level or template-level rating, set metadata.semanticType to "section_rating" (one per section, must be a rated type) or "overall_rating" (one per template, must be a rated type).
create_talent_pool_candidate
ChatGPTAdd a candidate to the talent pool when there is no specific job to match them to but they are a good prospect for future opportunities. Unlike create_candidate, no job shortcode is needed — the candidate is stored in the talent pool and can be matched to a job later. Supports the same fields as create_candidate except answers.
create_time_entry
ChatGPTCreate a complete time entry (clock-in and clock-out) for an employee in a single call. Use clock_in / clock_out for open-ended shifts
create_timeoff_request
ChatGPTCreates a new time off request. Use get_timeoff_categories to discover category_id values.
delete_department
ChatGPTDelete a department by its ID. Use force to delete even if the department has associated data.
delete_member
ChatGPTRemove (deactivate) a member from the account, revoking their access — used for offboarding workflows. This is a reversible deactivation, not a hard delete: the member can be reinstated later with enable_member. On success returns a confirmation (the endpoint returns 204 with no body). An error is returned if the member ID does not exist (404) or the member cannot be removed due to account restrictions, e.g. they are the sole admin (422).
disqualify_candidate
ChatGPTDisqualify a candidate from a job. Use this tool with candidate IDs obtained from get_candidates or get_candidates_by_job_name tools. IMPORTANT: Before calling this tool, use get_disqualification_reasons to retrieve the available disqualification reason IDs for the account.
enable_member
ChatGPTRe-enable (restore) a previously deactivated member, reinstating their access. This action is idempotent: enabling an already-active member succeeds as a no-op (it is not an error). On success returns a confirmation (the endpoint returns no body, and enablement may propagate asynchronously, so the member is not fetched afterwards — use get_members to read the refreshed state). An error is returned if the member ID does not exist (404) or the member could not be restored (422).
get_account_custom_attributes
ChatGPTGet all custom attributes configured for the account. Each attribute includes a question_key ("CA_<id>"): pass it as the question_key of an answer to create_candidate / update_candidate to set the attribute on a candidate.
get_accounts
ChatGPTGet all Workable accounts accessible to the authenticated user. Call this first to discover the available accounts before invoking any other tool, and use the returned subdomain as the account parameter.
get_candidate
ChatGPTGet detailed information for a specific candidate by ID. Use this tool with candidate IDs obtained from get_candidates or get_candidates_by_job_name tools.
get_candidate_activities
ChatGPTGet activities for a specific candidate by ID. Returns a list of actions taken on the candidate such as stage changes, comments, and other events.
get_candidate_activity
ChatGPTGet details for a specific activity on a candidate.
get_candidate_detailed_fields
ChatGPTReturns all available candidate fields with their types and search capabilities. Fields with search_field can be used as filters in search_candidates_detailed. When filter_type is "dropdown", use get_candidate_detailed_filter_options to fetch the allowed values.
get_candidate_detailed_filter_options
ChatGPTReturns the available values for a dropdown candidate filter field. Pass the search_field value from get_candidate_detailed_fields as filter_id.
get_candidate_files
ChatGPTList files attached to a specific candidate (resume, cover letter, and other uploaded documents). Each file includes its name, source, optional kind, and a preview URL.
get_candidate_offer
ChatGPTGet the offer for a specific candidate by ID
get_candidates
ChatGPTList candidates with advanced filtering options. Provide a job shortcode to list candidates for a specific job, or omit it to search across all jobs in the account (e.g. by email to resolve a candidate ID). Returns candidate IDs that can be used with get_candidate, disqualify_candidate, or move_candidate tools for further actions.
get_departments
ChatGPTList all departments in your Workable account.
get_disqualification_reasons
ChatGPTGet all available disqualification reasons in your Workable account
get_employee
ChatGPTGet details for a specific employee by ID
get_employee_documents
ChatGPTList documents associated with a specific employee. Supports filtering by document type. If you do not have the employee ID, use the
get_employees tool first to look it up by name or email. Document types: - simple_employee_document: documents uploaded directly to the employee profile. - signature_request_employee_document: documents created from a signature request. - timeoff_attachment: files attached to time off requests. - i_9_form_document: I-9 employment eligibility verification form documents (US-only). Access requires the caller to be the employee themselves or a member with the SignaturesView permission; otherwise the API returns 403.get_employee_fields
ChatGPTReturns all available employee fields with their types and search capabilities. Fields with search_field can be used as filters in search_employees. When filter_type is "dropdown", use get_employee_filter_options to fetch the allowed values.
get_employee_filter_options
ChatGPTReturns the available values for a dropdown employee filter field. Pass the search_field value from get_employee_fields as filter_id.
get_employees
ChatGPTList employees in your Workable account. The response includes a total_count field indicating the total number of employees matching the filters — use this to answer count questions without fetching all records. Start with a small limit (10 or 20) and only increase to 50 if you specifically need to retrieve a large dataset.
get_event
ChatGPTGet detailed information for a specific event by its ID. Use this tool when the user requests details about a specific event from the get_events results. The event ID should be obtained from the get_events tool response.
get_events
ChatGPTGet events from your Workable account with optional filtering. Returns a numbered list of events with their IDs for easy reference. After showing the results, ask the user if they would like to get detailed information about any specific event, then use the get_event tool with the event ID.
get_job
ChatGPTGet details for a specific job by shortcode
get_job_activities
ChatGPTGet activities for a specific job
get_job_application_form
ChatGPTGet application form for a specific job
get_job_custom_attributes
ChatGPTGet custom attributes for a specific job. Each attribute includes a question_key ("CA_<id>"): pass it as the question_key of an answer to create_candidate / update_candidate to set the attribute on a candidate.
get_job_members
ChatGPTGet members for a specific job
get_job_recruiters
ChatGPTGet external recruiters for a specific job
get_job_stages
ChatGPTGet stages for a specific job
get_jobs
ChatGPTReturns up to 10 jobs by default. By default only published jobs are returned; closed, draft, and archived jobs are excluded. If you are looking for a specific job or its candidates and find nothing, retry with state: 'closed', 'archived', or 'draft' before concluding the job does not exist. If more jobs are available, the response will include a since_id value you can use to fetch the next page.
get_legal_entities
ChatGPTGet all legal entities in your Workable account
get_members
ChatGPTList members of the Workable account, one page at a time (10 by default, up to 20). Returns active members unless status is set to 'inactive' or 'all'; page with since_id / max_id, or filter by role, job shortcode, email or exact name. Use it to find member IDs for revert_disqualification, upsert_candidate_rating, update_member, enable_member and delete_member.
get_offer
ChatGPTGet details for a specific offer by its ID
get_orgchart
ChatGPTGet the organization chart for employees in your Workable account
get_permission_sets
ChatGPTList the custom permission sets defined on your Workable account. Use this to discover the permission set names to include in the
roles array of invite_member / update_member: pass the permission set's name (not its id). A member can hold both a built-in role (ats./hris./workable.superadmin) and one or more permission sets, so these may be combined in the roles array. Returns each permission set's id, name and localized label/description.get_profile_update_fields
ChatGPTReturns all available profile update fields with their types and search capabilities. Fields with search_field can be used as filters in search_profile_updates. When filter_type is "dropdown", use get_profile_update_filter_options to fetch the allowed values.
get_profile_update_filter_options
ChatGPTReturns the available values for a dropdown profile update filter field. Pass the search_field value from get_profile_update_fields as filter_id.
get_requisition
ChatGPTGet details for a specific requisition by its code
get_requisitions
ChatGPTReturns requisitions with optional filtering. If more requisitions are available, the response will include paging info.
get_review
ChatGPTFetch a single review by its id (the template merged with any persisted answers — i.e. the autosaved draft). Returns { review, questionnaire }. Use this to load a review before writing, or to resume filling one in after a previous save. The caller must be the assigned reviewer of the review (the reviewee for self-reviews). Discover review ids from active_tasks[].reviews[].id via list_review_tasks.
get_review_aggregate
ChatGPTFetch the full review aggregate for an employee within a cycle, including aggregate status/state, the reviewee, the manager, the cycle, and every review visible to the caller (each as { review, questionnaire }). Peer / upward reviewers only see their own assigned review. Use the reviewee employee id (e.g. from active_tasks[].reviewee.id or an active_tasks[].actions.view URL).
get_review_cycle
ChatGPTGet a specific performance review cycle by ID, including dates, deadlines, counts and which review types are configured.
get_review_cycle_template
ChatGPTGet a specific performance review cycle template by ID, including its sections and questions
get_review_cycle_templates
ChatGPTList performance review cycle templates with optional pagination
get_review_cycles
ChatGPTList performance review cycles visible to the account, with optional pagination and state filtering. Archived/deleted cycles are not returned.
get_review_form
ChatGPTFetch the questionnaire form for a specific review type on a preparation task. Returns the underlying review (with status and template ids) and the questionnaire (sections + questions). Use list_review_tasks to discover task ids and the review types available on each task.
get_stages
ChatGPTGet all available recruitment pipeline stages in your Workable account
get_timeoff_balances
ChatGPTGet time off balances for an employee (or all employees if no employee_id provided)
get_timeoff_categories
ChatGPTGet all time off categories configured for the account
get_timeoff_requests
ChatGPTGet time off requests within a date range
get_work_schedules
ChatGPTGet all work schedules in your Workable account
invite_member
ChatGPTInvite a new member to the Workable account, creating a pending invitation. Use this for provisioning access as part of an onboarding or access-management workflow. On success returns the created invitation object (including its ID), not a member. Notes: the email must not already belong to an existing member or a pending invitation (otherwise 422); an invalid role or permission-set name is rejected (422); collaboration rules are only applied when the account subscription supports them, and member-limit and permission-set compatibility checks apply. When the account is authenticated with an account token you must supply member_id (the acting inviter); with a member token the authenticated member is used.
list_review_cycle_answers
ChatGPTBulk-pull persisted review answers in a cycle for reporting. Returns every answer the caller has access to: for a manager that is their reporting line (their reviewees across the org tree); an account admin with the ReviewCyclesView permission gets the entire cycle. By default only submitted reviews are returned — pass include_drafts=true to include draft answers as well. When the underlying review is anonymous, the reviewer is returned as { id: null, name: "Anonymous" }.
list_review_tasks
ChatGPTList the review tasks assigned to the authenticated member for a given review cycle. Returns two groups: — preparation_tasks: review aggregates whose templates the caller (as the aggregate manager) still needs to customize. Returned regardless of cycle state. — active_tasks: aggregate-centric tasks the caller can act on. Each task carries a reviewee, the aggregate-level actions (view / share / sign) the caller is entitled to, and a reviews[] array. Each review has an id, type (manager / self / peer / upwards), state, deadlines, and its own actions (view / write) URLs. Use a review's id with get_review / submit_review, and the aggregate (task) id with share_review / sign_review. Submitted reviews stay listed with a view-only action.
list_time_entries
ChatGPTList time tracking entries with optional filtering by date range, employees, type, or duration
mark_review_task_ready
ChatGPTFinalise every customizable review form on a preparation task. Once marked ready in an active cycle, the forms can no longer be edited via update_review_form, so confirm with the user before calling this.
merge_department
ChatGPTMerge a department into another target department. All associated data will be moved to the target department.
move_candidate
ChatGPTMove a candidate to a different stage in the hiring process. Use this tool with candidate IDs obtained from get_candidates tools.
reject_offer
ChatGPTReject an offer by its ID
reject_requisition
ChatGPTReject a requisition by its code, as the caller. Only works on a requisition that is pending and awaiting the caller's approval; any other requisition (already approved or rejected, or waiting on another approver) is reported as not awaiting approval.
relocate_candidate
ChatGPTRelocate a candidate to a different job, deleting the original candidate from the source job. This is like copy_candidate but destructive — the source candidate is removed. The candidate is added to the target job at the specified stage (or the default starting stage if not provided). Use this tool with candidate IDs obtained from get_candidates tools.
revert_disqualification
ChatGPTRevert a previously disqualified candidate, restoring them to active status on the job. Use this tool with candidate IDs obtained from get_candidates or get_candidate tools.
search_candidates_detailed
ChatGPTSearch candidates with filters and column selection. Call get_candidate_detailed_fields first to discover available columns and their search operators. For dropdown fields, call get_candidate_detailed_filter_options to get valid values before filtering.
search_employees
ChatGPTSearch employees with filters and column selection. Call get_employee_fields first to discover available columns and their search operators. For dropdown fields, call get_employee_filter_options to get valid values before filtering.
search_jobs
ChatGPTFind jobs by a partial or full job title and get back each match's shortcode, title, state, and id. Use this when you have a job name (e.g. 'Software Engineer') but not its shortcode: the returned shortcode can be passed directly to other job-scoped tools such as get_candidates, get_job_stages, and get_job_members. Only published jobs are returned by default; pass state to search closed, draft, or archived jobs.
search_profile_updates
ChatGPTSearch profile updates with filters and column selection. Call get_profile_update_fields first to discover available columns and their search operators. For dropdown fields, call get_profile_update_filter_options to get valid values before filtering.
share_review
ChatGPTShare the entire review aggregate with the reviewee, sending the share notifications. Operates on the aggregate as a whole (not a single review type) and requires the manager review to have been submitted first. Authorized caller: the aggregate manager. Returns the updated employee-aggregate shape. Pass the aggregate (preparation/active task) id, not a review id.
sign_review
ChatGPTRecord the calling member's signature on a shared review aggregate. Operates on the aggregate as a whole. Authorized callers: the reviewee and/or the manager on a shared aggregate. Confirm with the user before calling — signing is final. Returns the updated employee-aggregate shape. Pass the aggregate (preparation/active task) id, not a review id.
submit_review
ChatGPTFill in a review identified by its id. The caller must be the assigned reviewer (the reviewee for self-reviews). Discover review ids from active_tasks[].reviews[].id via list_review_tasks. Use action="save" to autosave a draft — repeated calls upsert answers by question_id, keeping the review in "draft" state. Use action="submit" to finalise the review — the API runs mandatory-question and required-rating validations and transitions the review to "submitted". Submitted reviews cannot be edited again (a second submit returns 409), so confirm with the user before submitting. Each answer's question_id MUST be a UUID present on the review's resolved template (call get_review to discover them). Pass
answer as HTML for long-text questions, and choices as a string array (e.g. ["yes"] for booleans, ["4"] for numeric/star ratings). Returns the updated { review, questionnaire } envelope.update_candidate
ChatGPTUpdate an existing candidate's profile with a partial set of fields — only the fields you provide are changed; everything else is left untouched. Recommended flow: call get_candidate first to read the current state, and get_job_custom_attributes / get_account_custom_attributes to discover custom field keys and valid values before setting them via
answers. Writable fields: firstname, lastname, email, phone, address, headline, summary, notes, cover_letter, texting_consent, skills, tags, social_profiles, experience_entries, education_entries, image_url/image, resume_url/resume, and custom attributes (via answers, keyed by question_key). There is no single name field — set firstname and/or lastname instead. Format constraints: email must be a valid email address; social_profiles[].url and image_url/resume_url must be valid URLs; dates use YYYY-MM-DD. Note: tags and skills are full replacements (the array you pass overwrites the existing set). To add while keeping existing values, read them with get_candidate and merge first. You can pass the full candidate object returned by get_candidate straight back in: read-only fields (e.g. id, name, job, stage, stage_kind, disqualified, sourced, profile_url, created_at, updated_at, hired_at) are accepted and ignored, so only the writable fields above take effect. One exception: account is the account subdomain string this tool operates on, not the candidate's account object — set it to the subdomain, not the object from get_candidate. Returns the full updated candidate object.update_candidate_tags
ChatGPTReplace the full set of tags on a candidate. The provided tags array overwrites any existing tags — passing an empty array clears all tags. To add a tag while keeping existing ones, fetch the candidate first with get_candidate and merge the existing tags into the new array.
update_department
ChatGPTUpdate an existing department.
update_member
ChatGPTUpdate an existing member's roles, permissions, or access scope. Updates are partial — only the fields you provide are changed; all other fields remain untouched. There is no editable name via this endpoint. Returns the full updated member object on success. Errors: the member ID must exist (otherwise 404); an invalid value for any field, or a member in a pending state, is rejected (422).
update_requisition
ChatGPTUpdate an existing requisition by its ID. Only the supplied fields are changed. The requisition code, linked job, and department cannot be modified through this tool. Every update stores a new version of the requisition with a new id (returned in the response); the previous id can no longer be updated, so use the returned id for any further update.
update_review_form
ChatGPTCreate or replace the questionnaire form for a specific review type on a preparation task. The whole questionnaire is replaced — pass the full set of sections and questions you want, not a partial diff. All body fields (section body, question body) must be non-empty strings — use a label like "Section rating" / "Overall rating" for rating questions rather than an empty string. Valid question types: "paragraph" (long text), "star_rated" (1-5 stars), "custom_rated" (labeled scale via metadata.ratingOptions), "numeric_rated" (numeric score), "multiple_choice" (options via metadata.answerOptions.choices). To mark a question as the section-level or template-level rating, set metadata.semanticType to "section_rating" (one per section, must be a rated type) or "overall_rating" (one per template, must be a rated type). Editing is rejected if the review cycle does not allow manager overwrite, or if the cycle is active and the form has already been marked ready.
update_time_entry
ChatGPTUpdate an existing time entry. At least one of clock_in_time, clock_out_time, or note must be provided. Pass note as null to clear it
update_timeoff_approval
ChatGPTApproves or rejects a pending time off approval. The key is the id from the pending_approvals array returned by get_timeoff_requests.
upsert_candidate_rating
ChatGPTCreate or update a candidate rating. Keyed on (candidate, member, stage): if a rating already exists for that combination it is updated, otherwise a new one is created. Use add_review when you specifically want create-only semantics.
Capabilities
Writes
