What the assistant can do

Once connected, ask your assistant for Recruitly data or changes in plain English. It picks the right tool for the job from the list below. Tools marked Reads only look at data. Tools marked Creates or Updates change records and only work when a Super user has switched on Allow AI assistants to make changes (see Access control). Every tool runs as you, with your normal Recruitly permissions.

Statuses, pipelines, stages, sources, sectors and similar options are configured per account, so the assistant reads them first (see Reference data) and then uses the right ids for your account.

Candidates

Search candidates with any mix of keyword, location, skills, status, source, tags, owner or saved search, read full profiles including the CV text, and create or update candidates. Updates cover the main fields, status, source, overview, internal notes, tags, address and expected salary in one call. A CV file can be parsed straight into a new candidate, either from a download link (fileUrl) or from the file contents (contentBase64). See Sending files.

Tool	What it does	Reads or writes
create_candidate	Create a new candidate in Recruitly. More Create a new candidate in Recruitly. Recruitly checks for an existing candidate with the same email, LinkedIn profile, or first name + surname + current employer; when one exists nothing is created and the result is { duplicate: true, id } with the existing candidate id, so update that record instead. Owner defaults to the signed-in user. statusId and sourceId must come from list_options (candidateStatuses, sources). Tags are group/value pairs. Address and expected salary fields need the current Recruitly release. Returns the new id and the created profile.	Creates
get_candidate_cv	Get a temporary download link to a candidate CV/resume file. More Get a temporary download link to a candidate CV/resume file. Use this only when someone needs the actual document to open or save — to READ what the CV says, use get_candidate_profile with includeCv instead, which returns the extracted text. The link expires after 15 minutes.	Reads
get_candidate_profile	Full candidate profile by ID, including work history, education and notes. More Full candidate profile by ID, including work history, education and notes. Set includeCv to read the actual CV/resume content.	Reads
list_custom_fields	List the custom (user-defined) field definitions configured on this account: id, label, inputType (INPUT_TEXT, INPUT_NUMBER, INPUT_DATE, YES_NO, DROPDOWN, MULTI_SELECT, ...), recordTypes, allowedValues for list fields and whether the field is mandatory. More List the custom (user-defined) field definitions configured on this account: id, label, inputType (INPUT_TEXT, INPUT_NUMBER, INPUT_DATE, YES_NO, DROPDOWN, MULTI_SELECT, ...), recordTypes, allowedValues for list fields and whether the field is mandatory. Use it to understand the customFields block returned on records. Filter by recordType or omit it for every record type.	Reads
list_saved_searches	List the candidate saved searches on this account (name, id, who created it, whether it is shared). More List the candidate saved searches on this account (name, id, who created it, whether it is shared). Pass an id as savedSearchId to search_candidates to run that saved search.	Reads
parse_candidate_cv	Create a candidate from a CV/resume file (pdf, doc or docx), sent as base64 (small files) or as an https link Recruitly downloads it from (fileUrl, preferred for anything over a few hundred KB): Recruitly parses the document into a candidate record and attaches the file as the CV. More Create a candidate from a CV/resume file (pdf, doc or docx), sent as base64 (small files) or as an https link Recruitly downloads it from (fileUrl, preferred for anything over a few hundred KB): Recruitly parses the document into a candidate record and attaches the file as the CV. If a candidate with the same email, or name and current employer, already exists, the existing candidate is returned with duplicate: true and the file is NOT attached. Parsing is rate limited per account plan. Returns candidateId, reference, name, duplicate, cvFileId and cvFileName; call get_candidate_profile with the candidateId to review what was parsed.	Creates
search_candidates	Search candidates in Recruitly. More Search candidates in Recruitly. All filters optional — omit everything to list all candidates (totalCount gives the account total).	Reads
update_candidate	Update a candidate. More Update a candidate. Only the fields you pass are changed; everything else is left as it is. Ids: statusId from list_options().candidateStatuses, sourceId from list_options().sources, referrerId is the id of the candidate or contact who referred them (omitting referrerId while passing sourceId clears any existing referrer). overview and internalNotes replace the whole text. Tags: addTags and removeTags change individual tags (matched on value, and on group when given); tags replaces the full list and an empty list clears all tags, which needs confirmClearTags: true. Tags, address and expected salary (desiredSalary, desiredSalaryCurrency, desiredSalaryTenure, noticePeriod) need the current Recruitly release. Returns { id, updated: [groups changed], record } with the updated profile.	Updates

Try:

• "Find Java developers in Manchester with a notice period of one month or less"
• "Read Priya Shah's CV and summarise her last three roles"
• "Set Tom Blake's expected salary to 55,000 per year and add the tag Sector: Finance"

Jobs and pipelines

Search jobs by keyword, status, client, employment type, pay or tags, read the full job with its candidate pipeline and stage counts, create jobs, update job fields and status, and move candidates through the pipeline.

Tool	What it does	Reads or writes
add_candidate_to_job	Add a candidate to a job pipeline. More Add a candidate to a job pipeline. If the candidate is already in that pipeline, the existing entry is returned unchanged.	Updates
create_job	Create a new job (vacancy) for a client company and contact, owned by the signed-in user.	Creates
get_job_detail	Full job detail by ID, optionally including the candidate pipeline and stage stats.	Reads
get_job_pipeline	Paged list of the entries in a job's candidate pipeline: pipeline entry id, candidate id and name, status code, stage name, rejected flag and when the candidate was added. More Paged list of the entries in a job's candidate pipeline: pipeline entry id, candidate id and name, status code, stage name, rejected flag and when the candidate was added. Use it when you need entry ids or rejected flags; get_job_detail already gives the candidates with stage counts for an overview.	Reads
list_job_stages	List the pipeline stages available for a job. More List the pipeline stages available for a job. Call this before add_candidate_to_job or move_pipeline_stage.	Reads
move_pipeline_stage	Move a candidate to a different stage in a job pipeline. More Move a candidate to a different stage in a job pipeline. The candidate must already be in that job's pipeline.	Updates
search_jobs	Search jobs/vacancies in Recruitly. More Search jobs/vacancies in Recruitly. For open/closed/on-hold/placed questions ALWAYS use systemFilter (e.g. OPEN_JOBS for "how many open jobs") — it works on every account. Only use status for account-specific status names from list_options().jobStatuses. totalCount in the response gives the overall count.	Reads
update_job	Update a job. More Update a job. Only the fields you pass are changed. Core fields (title, descriptions, openings, skills, dates, pay, employment type, experience level, remote flag, custom fields) are saved together; statusId (with optional reasonId and comments) changes the status; sourceId (with optional referrerId) changes the source; tags replaces every tag while addTags/removeTags merge with the current tags. To change the client company, contact, owner or status use the dedicated fields or tools; hot/visa/relocation/flexi-hours flags cannot be set through the API. Returns the updated job.	Updates
update_job_status	Change a job's status (for example open, on hold, filled, closed), optionally recording a reason and a comment.	Updates

Try:

• "How many open jobs do we have, and which clients are they for?"
• "Show the pipeline for the Senior Accountant job at Acme and who is at interview stage"
• "Add Priya Shah to the Data Analyst job and move her to the CV Sent stage"

Contacts

Search client contacts by name, company, email, sector, owner, tags or location, read the full contact record, and create or update contacts, including their status, source, overview, internal notes and tags.

Tool	What it does	Reads or writes
create_contact	Create a client contact at an existing company, owned by the signed-in user unless ownerId is given. More Create a client contact at an existing company, owned by the signed-in user unless ownerId is given. Search first (search_contacts) to avoid duplicates; when Recruitly finds a matching contact (same email, LinkedIn, or name at the same company) nothing is created and the result is { duplicate: true, id } with the existing contact id, so update that record instead.	Creates
get_contact	Full contact record by id or CT- reference: names, company, phones, status, source, owner, tags, skills, custom fields, do-not-contact flag. More Full contact record by id or CT- reference: names, company, phones, status, source, owner, tags, skills, custom fields, do-not-contact flag. Ids come from search_contacts.	Reads
search_contacts	Search contacts (clients, hiring managers) in Recruitly. More Search contacts (clients, hiring managers) in Recruitly. All filters optional; omit everything to list all contacts (totalCount gives the account total). Use get_contact for the full record of one result.	Reads
update_contact	Update a client contact. More Update a client contact. Only the fields you pass are changed. Core fields go to the contact record; statusId, sourceId/referrerId, overview, internalNotes and tags are applied through their own endpoints. tags replaces the whole tag list (an empty list needs confirmClearTags: true); addTags/removeTags merge into the current tags. Returns { id, updated: [groups], record }.	Updates

Try:

• "Who are our contacts at Acme Corp and when did we last speak to them?"
• "Create a contact called Jane Doe, Head of Talent at Acme, email [email protected]"
• "Change Mark Lee's status to Active Client and tag him Priority"

Companies

Search companies by name, status, sector, size, tags or owner, read the company record, see the full client history (jobs, placements, contacts and activity) and create or update companies.

Tool	What it does	Reads or writes
create_company	Create a client company, owned by the signed-in user unless ownerId is given. More Create a client company, owned by the signed-in user unless ownerId is given. A company whose name already exists (case-insensitive) is not created: the result is { duplicate: true, id } with the existing company id, so update that record instead.	Creates
get_client_history	Full client relationship history for a company: jobs, placements, contacts and recent activity.	Reads
get_company	Full company record by id or CY- reference: contact details, domain, status, owner, parent company, industry, sector, size, rating, tags, custom fields, active job and placement counts. More Full company record by id or CY- reference: contact details, domain, status, owner, parent company, industry, sector, size, rating, tags, custom fields, active job and placement counts. Ids come from search_companies. For jobs, placements, contacts and activity at the company use get_client_history.	Reads
search_companies	Search companies in Recruitly. More Search companies in Recruitly. All filters optional; omit everything to list all companies (totalCount gives the account total). Use get_company for the full record of one result.	Reads
update_company	Update a client company. More Update a client company. Only the fields you pass are changed. Core fields go to the company record; statusId, sourceId/referrerId, overview, internalNotes and tags are applied through their own endpoints. tags replaces the whole tag list (an empty list needs confirmClearTags: true); addTags/removeTags merge into the current tags. Returns { id, updated: [groups], record }.	Updates

Try:

• "Give me the full history with Acme Corp: jobs, placements and recent activity"
• "Which companies in the Technology sector have no open jobs?"
• "Update Acme's website and set its status to Key Account"

Leads

Leads are prospective clients that have not yet been converted into a contact or company. Search them, read their details, create new leads and move them through the lead pipeline.

Tool	What it does	Reads or writes
convert_lead	Convert a lead into a contact, a candidate or a deal, the same as Convert in the app. More Convert a lead into a contact, a candidate or a deal, the same as Convert in the app. The new record gets the lead's details, notes, files and custom fields, and the lead itself is REMOVED. Converting to a contact or a deal attaches it to a company: the lead's linked company (companyId on create_lead/update_lead), otherwise the company with the lead's company name, created if none exists; a lead with neither cannot be converted. Converting to a candidate needs ATS access. A deal needs title; stateId comes from list_options.opportunityStates (the first state when omitted), dates are YYYY-MM-DD and a forecastedClosingDate needs a startDate and must not be before it, bidCurrency is an ISO code the account has. Confirm with the user before calling. Returns { convertedTo, id, reference, leadRemoved } and, for a deal with a value, valueSet.	Updates
create_lead	Create a lead (a prospective client that is not yet a contact or company). firstName is required unless fromContactId is given; the owner defaults to the signed-in user. More Create a lead (a prospective client that is not yet a contact or company). firstName is required unless fromContactId is given; the owner defaults to the signed-in user. Ids come from list_options (leadStatuses, sources, industries, sectors; lead status names can repeat across pipelines, so pick by id and, when present, typeCode), list_users (ownerId) and list_custom_fields. If Recruitly already has a matching lead the result is { duplicate: true, id } and nothing is created. To make a lead out of someone who is already a contact, pass fromContactId: the contact's details fill every field you leave out, its company is linked, and the lead records which contact it came from. That only works when the account allows contacts as leads; otherwise the error says which setting to turn on.	Creates
get_lead	Full lead record by id or LD- reference: contact details, company name, status and pipeline, source, industry, sector, owner, rating, tags, custom fields and description.	Reads
search_leads	Search leads (prospective clients not yet converted to a contact or company) in Recruitly. More Search leads (prospective clients not yet converted to a contact or company) in Recruitly. Not for opportunities (deals): use search_opportunities for those. All filters optional; omit everything to list all leads.	Reads
update_lead	Update a lead. More Update a lead. Only the fields you pass are changed; each group is routed to the right Recruitly endpoint. statusId moves the lead through its pipeline (ids from list_options.leadStatuses; names can repeat across pipelines, so pick by id and, when present, typeCode such as OPEN, WORKING or CLOSED). sourceId sets the source (with optional referrerId), overview replaces the description text, tags replaces the full tag list (pass confirmClearTags to clear it) while addTags/removeTags change individual tags. doNotContact and website cannot be changed through this tool. Returns { id, updated, record }.	Updates

Try:

• "List my open leads in the Healthcare sector"
• "Create a lead for Sam Patel at Nova Labs from the LinkedIn source"
• "Move the Nova Labs lead to Working and add a note about today's call"

Opportunities

Opportunities are sales deals tracked through a pipeline of states such as Open, Won or Lost. Search them, read the deal, create new opportunities and update their state, value, dates and tags.

Tool	What it does	Reads or writes
create_opportunity	Create an opportunity (sales deal). More Create an opportunity (sales deal). Only name is required; the owner defaults to the signed-in user and the company is filled from the contact when only contactId is given. stateId comes from list_options.opportunityStates (state names can repeat across pipelines, so pick by id and, when present, typeCode such as OPEN); companyId from search_companies, contactId from search_contacts, ownerId from list_users, custom field ids from list_custom_fields. A forecastedClosingDate needs a startDate and must not be before it.	Creates
get_opportunity	Full opportunity record by id or OP- reference: name, company, contact, state and reason, bid value and currency, probability, start and closing dates, owner, tags, custom fields and description.	Reads
search_opportunities	Search opportunities (sales deals with a company or contact, tracked through a pipeline of states such as Open, Won or Lost) in Recruitly. More Search opportunities (sales deals with a company or contact, tracked through a pipeline of states such as Open, Won or Lost) in Recruitly. Omit query to list all opportunities, newest first. Not for leads: use search_leads for those.	Reads
update_opportunity	Update an opportunity. More Update an opportunity. Only the fields you pass are changed; each group is routed to the right Recruitly endpoint. stateId moves the deal through its pipeline and is the way to mark it Won or Lost (ids from list_options.opportunityStates; names can repeat across pipelines, so pick by id and, when present, typeCode such as WON or LOST; reasonId must be one of that state's reasons and comments are stored as a note). sourceId sets the source (with optional referrerId), tags replaces the full tag list (pass confirmClearTags to clear it) while addTags/removeTags change individual tags. estimatedDurationMonths and actualClosingDate cannot be changed through this tool. Returns { id, updated, record }.	Updates

Try:

• "Which opportunities are due to close this quarter and what are they worth?"
• "Create an opportunity called Acme RPO, 120,000 GBP, closing on 30 November"
• "Mark the Acme RPO opportunity as Won"

Placements

Read placements (successful hires) with fees, dates and consultant attribution, filter by period, client, consultant or type, and update a placement's status or tags.

Tool	What it does	Reads or writes
get_placement	One placement by id or PL- reference: candidate, company, job, status, type, dates, tags, custom fields and owner. More One placement by id or PL- reference: candidate, company, job, status, type, dates, tags, custom fields and owner. Money fields: feeBase is the placement fee converted to the account's base currency (the base currency code is not returned here), while salaryCurrency is the currency of salary, clientRate, candidateRate and margin. Never pair feeBase with salaryCurrency or add feeBase to the salary figures.	Reads
get_placements	List placements (successful hires) with fees and consultant attribution. More List placements (successful hires) with fees and consultant attribution. For period questions like "placements this month" or "who placed the most candidates" use systemFilter (e.g. PLACEMENTS_THIS_MONTH); use startDateFrom/startDateTo only for custom ranges.	Reads
update_placement	Update a placement: statusId changes its status (validated against list_options().placementStatuses); tags replaces every tag, addTags/removeTags merge with the current tags. More Update a placement: statusId changes its status (validated against list_options().placementStatuses); tags replaces every tag, addTags/removeTags merge with the current tags. Only what you pass is changed. Returns the updated placement.	Updates

Try:

• "List placements made this month and their fees"
• "Who placed the most candidates last quarter?"
• "Which temp placements are finishing in the next two weeks?"

Tasks

List your open tasks, read a task, create tasks linked to records, and mark tasks as done.

Tool	What it does	Reads or writes
complete_task	Mark a task as done. More Mark a task as done. Task ids come from list_tasks or create_task. Completing an already completed task is harmless.	Updates
create_task	Create a task for the signed-in user, linked to one or more candidates, contacts, companies or jobs.	Creates
get_task	Fetch one task by id (any task in the account, open or completed). More Fetch one task by id (any task in the account, open or completed). Task ids come from list_tasks or create_task.	Reads
list_tasks	List the signed-in user's open (not completed) tasks, overdue included, soonest due first, tasks with no due date last. More List the signed-in user's open (not completed) tasks, overdue included, soonest due first, tasks with no due date last. Covers tasks the user created, assigned or was assigned. Use hasMore to page. Each task carries id, subject, excerpt, status, dueDate, createdOn, createdBy, typeName, assignedTo and linkedRecords.	Reads

Try:

• "What tasks do I have due this week?"
• "Create a task to call Jane Doe at Acme on Friday about the Data Analyst role"
• "Mark the task about the Acme contract as done"

Users

Find the users (consultants) on your account, so the assistant can turn a name into the right owner, consultant or assignee, and see who is signed in.

Tool	What it does	Reads or writes
get_current_user	The signed-in Recruitly user behind this connection: id, name, email, mobile, role, jobTitle. More The signed-in Recruitly user behind this connection: id, name, email, mobile, role, jobTitle. Use the id when a tool needs the current user as consultantId or ownerId.	Reads
list_users	List the active users (consultants) in this Recruitly account. More List the active users (consultants) in this Recruitly account. Use it to resolve a person's name or email to the user id that other tools take as consultantId, ownerId or assignee. Optional query matches name or email (case-insensitive); role narrows to SUPER, TEAM_LEAD, TEAM_MEMBER, BILLING or SUPPORT. Returns at most 200 users with a truncated flag.	Reads

Try:

• "Which user is Alex Morgan, and what is their role?"
• "Show me the open jobs owned by Alex Morgan"

Activity and notes

Read the recent activity (notes, calls, emails, status changes) for a record, a consultant or the whole account, and add notes to any record with an optional activity type, linked records and reminder.

Tool	What it does	Reads or writes
add_note	Add a timeline note to a candidate, contact, company, job, lead, opportunity or placement. More Add a timeline note to a candidate, contact, company, job, lead, opportunity or placement. The note is recorded as written by the signed-in user. Optionally classify it with an activity type (by name via activityType, or by id via activityTypeId, both from list_options().activityTypes; omit for a plain comment), attach it to further records with linkedRecordIds (up to 20, any type; it then shows on each of their timelines) and set a reminder with reminderAt. Every record id is checked before the note is written.	Creates
get_activity_feed	Recent CRM activity (notes, calls, emails, status changes) — for a record, a consultant, or account-wide. More Recent CRM activity (notes, calls, emails, status changes) — for a record, a consultant, or account-wide. Time window runs from sinceHours ago up to untilHours ago (default now); page through results with page.	Reads

Try:

• "What happened on the Acme account in the last 48 hours?"
• "Add a note to Priya Shah: called today, available from 1 December, keen on hybrid roles"
• "Log a call against the Data Analyst job and Jane Doe, and remind me next Tuesday"

Analytics

Billing and revenue summaries from placements, consultant KPIs by month, and pipeline stage statistics for one job or all jobs.

Tool	What it does	Reads or writes
get_billing_summary	Billing/revenue summary from placements for a period, optionally per consultant.	Reads
get_consultant_performance	KPI performance metrics per consultant (placements, CVs sent, interviews, revenue) for a given month/year.	Reads
get_pipeline_stats	Hiring pipeline stage statistics — for one job or across all jobs.	Reads

Try:

• "What is our billing for this quarter, by consultant?"
• "Compare the team's CVs sent and interviews this month with last month"
• "Where are candidates dropping out of the pipeline across all open jobs?"

Files

List the documents on any record, get a temporary download link for a file, and attach documents, including formatted CVs, to a record, either from a download link (fileUrl) or from the file contents (contentBase64). See Sending files.

Tool	What it does	Reads or writes
get_file_link	Get a temporary download link for a file attached to a record, plus its name, content type and size. More Get a temporary download link for a file attached to a record, plus its name, content type and size. The link points straight at secure storage, needs no API key and expires 15 minutes after it is issued, so hand it to the person right away. fileId comes from list_files (or cvFileId from parse_candidate_cv). For the text of a candidate CV use get_candidate_profile with includeCv instead.	Reads
list_file_categories	List the file categories configured on this account as id and name pairs (for example CV, Formatted CV, Contract). More List the file categories configured on this account as id and name pairs (for example CV, Formatted CV, Contract). Use the id as categoryId in upload_file so the document lands in the right category; pick the Formatted CV category when uploading a formatted or branded CV.	Reads
list_files	List the documents attached to any Recruitly record (candidate, contact, company, job, lead, opportunity or placement), newest first, as shown on the record Files tab. More List the documents attached to any Recruitly record (candidate, contact, company, job, lead, opportunity or placement), newest first, as shown on the record Files tab. Each entry has the file id (for get_file_link), name, extension, size, categoryId/categoryName and who uploaded it. A file uploaded a moment ago may take a few seconds to appear.	Reads
upload_file	Attach a document to any Recruitly record (candidate, contact, company, job, lead, opportunity or placement), either by sending its contents as base64 (small files) or by giving an https link Recruitly downloads it from (fileUrl, preferred for anything over a few hundred KB). More Attach a document to any Recruitly record (candidate, contact, company, job, lead, opportunity or placement), either by sending its contents as base64 (small files) or by giving an https link Recruitly downloads it from (fileUrl, preferred for anything over a few hundred KB). Maximum 5 MB. To upload a formatted or branded CV to a candidate, first call list_file_categories and pass the matching category id as categoryId; without a categoryId the file is stored uncategorised. Only the file types allowed on the account are accepted; Recruitly rejects others with a message. Returns the stored file (id, name, size, record). Linking to the record happens asynchronously, so list_files may lag a moment before showing it.	Creates

Try:

• "What documents are attached to Priya Shah's record?"
• "Give me a download link for the latest contract on the Acme company record"
• "Upload this formatted CV to Priya Shah's record under the Formatted CV category"

Campaigns

List email marketing campaigns, read a campaign and its delivery and engagement statistics, and archive or restore campaigns.

Tool	What it does	Reads or writes
archive_campaign	Archive an email campaign so it leaves the live list (list_campaigns with archived: true still shows it; undo with unarchive_campaign). More Archive an email campaign so it leaves the live list (list_campaigns with archived: true still shows it; undo with unarchive_campaign). Archiving does not stop a send, so campaigns that are SCHEDULED, PREPARING or SENDING are refused. Nothing is deleted.	Updates
get_campaign	Fetch one email campaign by id (same fields as list_campaigns). More Fetch one email campaign by id (same fields as list_campaigns). Campaign ids come from list_campaigns.	Reads
get_campaign_stats	Delivery and engagement counters for a campaign (requests, dispatches, delivered, opens, uniqueOpens, clicks, uniqueClicks, softBounce, hardBounce, unsubscribes, spamComplaints, failures, rejects, drops) plus derived percentages: openRate = uniqueOpens / delivered, clickRate = uniqueClicks / delivered, bounceRate = (softBounce + hardBounce) / delivered. More Delivery and engagement counters for a campaign (requests, dispatches, delivered, opens, uniqueOpens, clicks, uniqueClicks, softBounce, hardBounce, unsubscribes, spamComplaints, failures, rejects, drops) plus derived percentages: openRate = uniqueOpens / delivered, clickRate = uniqueClicks / delivered, bounceRate = (softBounce + hardBounce) / delivered. All counters are zero and the rates are null when the campaign has not been sent yet (check status).	Reads
list_campaigns	List the account's email marketing campaigns, newest first. More List the account's email marketing campaigns, newest first. Filter by name/subject text (query), status (DRAFT, SCHEDULED, PREPARING, PAUSED, SENDING, FAILED, SENT, CANCELLED) and archived (true lists archived campaigns instead of live ones). Each campaign carries id, reference, name, subject, status, statusMessage, archived, suspended, sender, distribution list, scheduledOn, sentOn and owner.	Reads
unarchive_campaign	Restore an archived email campaign to the live list. More Restore an archived email campaign to the live list. Campaign ids come from list_campaigns with archived: true.	Updates

Try:

• "What was the open rate of last week's newsletter?"
• "List campaigns that are still in draft"
• "Archive the campaigns sent before January"

Drip campaigns

Design a drip campaign (a sequence of emails, SMS, WhatsApp messages and tasks sent to each recipient over days) with the assistant and save it to Recruitly as a draft. The assistant reads Recruitly's design guide first: the writing rules, the merge fields that exist and the format a campaign is saved in. Saving matches the statuses, tags, folders, jobs and pipeline stages you named to the ones in your account, corrects merge fields that do not exist, and tells you what it changed. A draft sends nothing: you add people and start it in Recruitly. It can also list your drip campaigns and read one.

Tool	What it does	Reads or writes
get_sequence	Fetch one drip campaign (sequence) with every step: wait time, subject and message per channel, what happens after each step, and its sending settings. More Fetch one drip campaign (sequence) with every step: wait time, subject and message per channel, what happens after each step, and its sending settings. Sequence ids come from list_sequences.	Reads
get_sequence_design_guide	Read this BEFORE writing a drip campaign (a "sequence": emails, SMS, WhatsApp messages and tasks sent to each recipient over days). More Read this BEFORE writing a drip campaign (a "sequence": emails, SMS, WhatsApp messages and tasks sent to each recipient over days). Returns the writing rules, the only merge fields that exist, the JSON format that save_sequence_draft accepts and an example. Design the campaign with the user in plain reading form first and change it until they are happy; convert it to the format only when they say it is final.	Reads
list_sequences	List the account's drip campaigns (sequences): id, name, audience, whether it is still a draft or switched off, and how many steps it has. More List the account's drip campaigns (sequences): id, name, audience, whether it is still a draft or switched off, and how many steps it has. Filter by name text (query) or audience. Returns at most 200 with a truncated flag.	Reads
save_sequence_draft	Save a drip campaign to Recruitly as a DRAFT. More Save a drip campaign to Recruitly as a DRAFT. Nothing is sent: the user adds people and starts it in Recruitly. Call it only when the user has said the campaign is final. design is the whole campaign as JSON text in the format from get_sequence_design_guide. Write statuses, tags, folders, jobs and pipeline stages by the names the user used; Recruitly matches them to the account's own and corrects merge fields that do not exist. The result lists what was adjusted and anything the user should check (tell them both), and a link to open the draft list in Recruitly. Each call creates a new draft; to change a saved campaign the user edits it in Recruitly.	Creates

Try:

• "Design a drip campaign for candidates for the Senior Accountant job at Acme: four steps over two weeks"
• "Make step two shorter and add a call reminder for me after it"
• "That's final, save it to Recruitly as a draft"
• "Show me the steps of my Client nurture drip campaign"

Account setup

Set up a Recruitly account by talking it through. The assistant reads what is configured now, asks about your agency, shows you a plan, and saves it once you agree. Today it can change the agency's own details (name, website, phone, address, timezone, date format), create job pipelines or add stages to them, and add entries to your pick lists: candidate, job, company, contact and placement statuses, company types, sources, sectors, industries, skills, job titles, reject reasons and tags. It only ever adds to a list; renaming, merging and deleting entries is done in Recruitly under Settings, Master data. It can also create teams and offices (never users: you invite your own team) and set your own email signature. Only Super users can change account setup, and billing currency is never changed. Removing or renaming a pipeline stage is done in Recruitly, because candidates may be sitting in it.

Tool	What it does	Reads or writes
add_list_options	Add entries to one of the account's pick lists, so they match how the agency works: candidateStatuses, jobStatuses, companyStatuses, contactStatuses, placementStatuses, companyTypes, sources, sectors, industries, skills, jobTitles, rejectReasons. More Add entries to one of the account's pick lists, so they match how the agency works: candidateStatuses, jobStatuses, companyStatuses, contactStatuses, placementStatuses, companyTypes, sources, sectors, industries, skills, jobTitles, rejectReasons. Super users only. Names that are already in the list are skipped, never duplicated. Some lists need a fixed type that tells Recruitly what each entry means, one type per call: candidateStatuses (ACTIVELY_LOOKING, CONSIDERING_OPPORTUNITY, FOUND_OWN_JOB, NOT_LOOKING, ON_CONTRACT, PLACED_BY_US, PLACED_BY_OTHERS), jobStatuses (OPEN, CLOSED, ON_HOLD), sources (WEBSITE, JOB_BOARD, SEARCH_ENGINE, SOCIAL_MEDIA, COLD_CALL, REFERRAL, PURCHASED_LIST, OTHER), rejectReasons (the job pipeline stage type the reason applies to: SOURCED, APPLIED, SHORTLIST, CV_SENT, INTERVIEW, OFFER, PLACED). This tool only adds; renaming, recolouring, reordering, merging and deleting are done in Recruitly under Settings, Master data. Use save_tags for tags. Call get_account_setup first to see what is already there.	Creates
add_team_or_office	Create a team or an office on the account. More Create a team or an office on the account. Super users only. A team groups users (e.g. "Perm", "Contract"); restrictDataAccess limits its members to their own team's records. An office is a location with an address and phone. This creates only: one whose name already exists is left alone and reported. Putting people into a team or office, and renaming or deleting one, is done in Recruitly under Settings, Users. This tool never creates, invites or changes users.	Creates
get_account_setup	Start here when asked to set up or review a Recruitly account. More Start here when asked to set up or review a Recruitly account. Returns how to run a setup conversation (guide), whether this user may change setup (canChange: Super users only), and what is configured now: agency profile, job pipelines with their stages, the seven fixed stage types, plan limits, and the names in the main lists (statuses, sources, sectors, skills). currency is shown but can never be changed. A part that could not be read is left out rather than guessed.	Reads
save_email_signature	Set the signed-in user's own email signature, the block added under the emails they send from Recruitly. More Set the signed-in user's own email signature, the block added under the emails they send from Recruitly. Replaces their current signature, so show the user the new one and get a yes first. Pass simple HTML: paragraphs, line breaks, bold, links. No images, scripts or styles. It changes only this user's signature, never anyone else's.	Updates
save_job_pipeline	Create a job pipeline (the stages a candidate moves through on a job), or add stages to an existing one. More Create a job pipeline (the stages a candidate moves through on a job), or add stages to an existing one. Super users only. Every stage belongs to one of six types: SOURCED, APPLIED, SHORTLIST, CV_SENT, INTERVIEW, OFFER; several stages may share a type (two interview rounds are two INTERVIEW stages). Stages always run in that type order, and the fixed "Placed" stage is added last automatically, so never pass it. To change an existing pipeline pass pipelineId and the full list of stages you want, including the ones it already has: stages can be added and reordered within a type here, but removing or renaming a stage is done in Recruitly (Jobs, Job settings, Workflows) because candidates may be sitting in it. Call get_account_setup first for existing pipelines and limits.	Creates
save_tags	Add tags to a tag category, creating the category if it does not exist. More Add tags to a tag category, creating the category if it does not exist. Tags are grouped in categories, e.g. category "Languages" with tags "French", "German". Super users only. This only ever adds: tags already in the category stay exactly as they are. Renaming or deleting a category or a tag is done in Recruitly under Settings, Master data, because records already carrying the tag are affected.	Creates
update_agency_profile	Change the agency's own details: name, website, phone, address, timezone and date format. More Change the agency's own details: name, website, phone, address, timezone and date format. Pass only what should change; everything else is kept as it is. Super users only. Billing currency is permanent and is never changed. Confirm the new values with the user before calling.	Updates

Try:

• "Set up my Recruitly account. Ask me about my agency first"
• "Create a pipeline for contract roles with two interview rounds"
• "Add a 'Client feedback' stage after CV sent on my default pipeline"
• "Change our timezone to Europe/Dublin"
• "Add our sectors: Fintech, Legal and Life sciences"
• "Add a 'Clearance' tag category with SC and DV"
• "Create a Contract team and a Manchester office"
• "Write me an email signature with my name, title and phone"

Reference data

The options configured on your account (statuses, pipelines and stages, activity types, sources, industries, sectors, skills, employment types and more), the custom fields defined on each record type, the file categories, and static lists such as countries and languages. The assistant uses these to pass the right ids to other tools; you rarely need to ask for them directly.

Tool	What it does	Reads or writes
list_lookup_data	Static system lookup lists shared by every account: countries, languages and nationalities as { code, name } pairs, plus recordTypes (the record type names the API uses). More Static system lookup lists shared by every account: countries, languages and nationalities as { code, name } pairs, plus recordTypes (the record type names the API uses). Use it to find the country or language code a tool expects. Pass types to return a subset; the data rarely changes, so one call per session is enough.	Reads
list_options	Returns the account's configured field options (master data) so you can pass the right ids and names to other tools: statuses, types, pipelines and stages, activity types, sources, industries, sectors, skills, employment types, education levels, genders. More Returns the account's configured field options (master data) so you can pass the right ids and names to other tools: statuses, types, pipelines and stages, activity types, sources, industries, sectors, skills, employment types, education levels, genders. Values are configured per account and may be in any language, so call this before filtering by status or type. By default returns jobStatuses, candidateStatuses and activityTypes; pass lists to pick any of the 23 lists (e.g. ["leadStatuses", "opportunityStates"]). Items are { id, name }; leadStatuses and opportunityStates also carry pipelineId, pipelineName and typeCode (leads: OPEN, WORKING, CLOSED; opportunities: OPEN, QUALIFYING, NEGOTIATING, SIGNING, WON, CONVERTED, LOST, SUSPENDED, ABANDONED), and opportunityStates carry reasons [{ id, name }], so pick a state by typeCode (e.g. WON) rather than by its label. Each list is capped at 200 entries; truncated names the lists that were cut.	Reads

Try:

• "What candidate statuses does our account use?"
• "Which custom fields do we have on jobs?"

Cross-record search

One search across candidates, jobs, contacts, companies, leads, opportunities and placements, plus a way to read any record from its id. ChatGPT's company knowledge and deep research use these two tools.

Tool	What it does	Reads or writes
fetch	Fetch the full content of a Recruitly candidate, job, contact, company, lead, opportunity (deal), placement or task by the id returned from the search tool (for example "candidate:<recordId>"). More Fetch the full content of a Recruitly candidate, job, contact, company, lead, opportunity (deal), placement or task by the id returned from the search tool (for example "candidate:<recordId>"). A bare record id without the type prefix is looked up and dispatched automatically. Returns the record as readable text with a link to it in Recruitly; the link is the linked job for a placement and the linked record for a task, or empty when there is none.	Reads
resolve_record	Look up any Recruitly record id and find out what it is: returns id, type (candidate, contact, company, job, lead, opportunity, placement, ...), label, email, mobile and reference. More Look up any Recruitly record id and find out what it is: returns id, type (candidate, contact, company, job, lead, opportunity, placement, ...), label, email, mobile and reference. Use it before calling a type-specific tool when you only have an id, or to confirm an id belongs to the type you expect.	Reads
search	Search Recruitly across candidates, jobs, contacts, companies, leads, opportunities (deals) and placements in one call. More Search Recruitly across candidates, jobs, contacts, companies, leads, opportunities (deals) and placements in one call. Returns up to 5 matches per record type (35 in total), each with an id to pass to the fetch tool for the full record, a descriptive title and a link to the record in Recruitly.	Reads

Try:

• "Search Recruitly for anything related to Acme"
• "What is record CY-1042?"

Sending files

upload_file and parse_candidate_cv take the file in one of two ways:

Input	Use it when	Limit
fileUrl	The file is already online: a link from get_file_link, a shared cloud-storage link, or any public https:// URL that downloads without signing in. Recruitly fetches it server-side.	5 MB, 20 seconds
contentBase64	The file is small and the assistant already holds its bytes. Every byte costs the assistant about 1.4 characters of output, so an 87 KB CV is roughly 116,000 characters typed into the tool call.	5 MB, but impractical above a few hundred KB

MCP tool calls carry no file attachments, so a file that only exists on your own computer cannot be sent by link. For those, upload through the Recruitly app or a browser-based assistant, then work with the record through the connector.

Deprecated tools

These tools still work but newer tools do the same job better. Assistants are told to prefer the replacements.

Tool	Use instead
list_jobs	search_jobs, which has richer filters including system filters such as open jobs
list_pipelines	get_pipeline_stats for stage statistics, or get_job_detail with the pipeline included

Not available

Action	Why
Deleting candidates, leads, opportunities, jobs, files or campaigns	Deletes are permanent, so they stay out of the connector until Recruitly can gate them behind their own setting
Cancelling a scheduled campaign	Held until Recruitly only allows cancelling campaigns that are still scheduled
Public job board endpoints (published jobs and their counts by sector, location, skill and so on)	These need a public job board key, and the connector always runs as a signed-in user
Downloading file contents directly	Files are large binary data; the assistant gets a temporary download link instead, and reads CV text through the candidate profile