AI Suggestions

AI Suggestions User Guide

How to use AI Suggestions on Requirements and Candidates in Colleague.
← Back to User Guides
 

The AI Suggestions module uses AI to match people and jobs in Colleague. On a Requirement, it ranks the candidates who best fit the job. On a Candidate, it finds the live jobs that fit the candidate and the contacts to put them forward to.

Feature Opened from What it finds Status
Suggested Candidates Requirement The candidates who best fit the job, ranked by score. Available
Suggested Requirements Candidate The live jobs that fit the candidate, ranked by score. Available
Suggested Contacts Candidate The contacts to spec the candidate to, based on live and past requirements. Available
AI Suggestions is available and enabled. Suggested Candidates opens the AI Suggested Candidates report, and Suggested Requirements and Suggested Contacts are available on Candidate records.
Settings
 
 
User Group Permissions
Permission What it does Default
AI Usage Grants access to AI Usage within the Admin area: AI tokens and estimated cost by date, user, feature and record (the requirement or candidate each AI matching run was for), and this month's spend against the AI allowance. Full Access
AI Suggested Candidates Allows a User to run AI Suggested Candidates from a Requirement (the AI reads each candidate's CV against the Requirement and uses AI credits). Only used while AI Suggested Candidates is switched on in Global Settings; without it the Suggested Candidates button runs the standard, non-AI suggestions output. Full Access
AI Suggested Requirements Allows a User to run AI Suggested Requirements from a Candidate's Submit menu (the AI reads each Live Requirement against the candidate's CV and uses AI credits). Only used while AI Suggested Requirements is switched on in Global Settings. Full Access
AI Suggested Contacts Allows a User to run AI Suggested Contacts from a Candidate's Submit menu (contacts to Spec CV the candidate to, from Live and past requirements read by the AI - uses AI credits). Only used while AI Suggested Contacts is switched on in Global Settings. Full Access
View the AI Usage Overview Grants the ability to view the AI Usage tab on the Home page: AI tokens and estimated cost by date, user, feature and record (the requirement or candidate each AI matching run was for) for the teams the user can report on, and this month's spend against the AI allowance. Full Access
 
Matching

These settings decide which candidates the AI reads on each run and how much of each CV and job description it sees.

Setting What it does Default
Additional instructions Free-text guidance added to the AI's brief every time it scores a candidate against a requirement. Use it for rules that apply across your business but won't always be written into a job description, for example "Favour candidates with public sector experience" or "A full UK driving licence is mandatory for all field-based roles". Keep instructions short and specific: vague or conflicting instructions make scores less consistent. Leave blank to have the AI score on the job description and CV alone. Blank (none)
Candidates read per run How many candidates go forward from the Candidate Pool stage to AI scoring on each run (5 - 200). Colleague first pre-ranks every candidate who meets the salary band, radius and CV requirements, then sends the top candidates, up to this number, to the AI. A higher number casts a wider net but uses more AI tokens and makes each run take longer. A lower number is faster and cheaper but may miss good candidates who were pre-ranked lower. 40
Candidate Type filter Yes/No. When set to Yes, candidates whose Candidate Type does not suit the requirement type are left out of the Candidate Pool before AI scoring, so no AI tokens are spent on them. For this to work, map each Candidate Type in Lookup Maintenance to the requirement types it suits (Suits Contract / Permanent / Rolling Contract / Fixed Term). When set to No, Candidate Type is ignored when building the pool. -
Default country The two-letter country code (for example GB or IE) used to look up a postcode when a candidate or requirement address has no country set. Postcode lookups give the locations used for the radius filter and the Distance score. Set this to the country where most of your candidates and jobs are based. If it is wrong, postcodes may not be found, which affects the radius filter and the Distance score. GB
CV length The maximum number of characters taken from each candidate's CV and sent to the AI. The default of 6000 characters is roughly 1,000 words, or two to three pages, which covers the recent career history on most CVs. Raising it lets the AI see more of longer CVs but uses more tokens for every candidate scored. Lowering it reduces cost, but experience further down a CV may not be read. 6000
Job description length The maximum number of characters taken from the requirement's job description and sent to the AI. The default of 4000 characters is roughly 650 words. The job description is sent alongside every candidate the AI reads, so each extra character is multiplied by the number of candidates read per run. Raise it if your job descriptions are long and key requirements appear near the end. 4000
Cached answer life How many days an AI answer is stored and reused. When a candidate has already been scored against a requirement, re-running the report within this period reuses the stored answer at no AI cost, as long as the candidate and job are unchanged. After this period the candidate is read and scored again. A shorter period gives fresher answers but costs more; a longer period saves tokens on requirements that are run repeatedly. 90
 
Usage Limits

These settings cap how many AI tokens, and how much money, AI matching can use. Every limit resets on the 1st of each month.

Setting What it does Default
MonthlySpendCapGBP Your monthly AI allowance in pounds, shared by all AI matching (Suggested Candidates, Suggested Requirements and Suggested Contacts). Spend is estimated from the tokens each run uses, at the prices shown on the AI Usage screen. When the allowance is used up, AI matching cannot run until the 1st of the next month, and users are told why. Suggested Candidates can still be run with Use AI scoring switched off. Track spend against the allowance on the AI Usage screen or the AI Usage tab on the Home page. 0 = no cap. -
Monthly token cap per feature The maximum number of AI tokens each AI matching feature (Suggested Candidates, Suggested Requirements, Suggested Contacts) may use per calendar month. Each feature has its own count, which resets on the 1st. Use this to stop one feature using up the whole allowance. It works alongside MonthlySpendCapGBP, which limits all features together; whichever limit is reached first stops AI matching for that feature. 0 = no cap. -
Tokens per run The maximum number of AI tokens a single run of the report may use. This stops one run, for example on a requirement with a very long job description or a high Candidates read per run, from using a large share of the monthly allowance. As a rough guide, each candidate read uses the CV, the job description and the AI's answer, so with the default lengths a run of 40 candidates fits well within 200000. If you raise Candidates read per run, CV length or Job description length, you may need to raise this too. 200000
Tokens per answer The maximum number of tokens the AI may use when answering for each candidate. The answer holds the fit score, summary, reasons, concerns, similar employers and competitor flag. The default of 400 is enough for concise answers. If it is set too low, answers can be cut short and the candidate may not be scored; they are then ranked on the remaining components and flagged. With some models, reasoning also counts towards this limit, so raise it if you increase Reasoning effort. 400
 
AI Performance

These settings control how fast runs complete and how much the AI reasons about each match.

Setting What it does Default
Parallel AI calls How many candidates the AI scores at the same time (1 - 16). Higher values make runs finish faster; the number does not change the cost. Your Azure OpenAI deployment has its own rate limits, however, and setting this above what the deployment allows can cause requests to be throttled, which slows runs down or leaves candidates unscored. If users see candidates flagged as not scored on busy days, lower this value. 8
Reasoning effort How much the AI works through a match before giving its answer: none, low, medium or high. Low or none is fastest and uses the fewest tokens, and suits most roles. Medium or high gives more careful judgement on complex or senior roles, but runs take longer and use more tokens. This only has an effect if your Azure OpenAI deployment uses a reasoning model. Leave blank to use the value set in Integrations. Blank (uses the Integrations value)
Suggested Candidates
 

On a Requirement, select the Suggested Candidates button. This opens the AI Suggested Candidates report, which ranks candidates for the job in two stages.

 
How Candidates Are Ranked
1
2
Candidate Pool
AI Scoring

Candidates are pre-ranked on four signals:

  • CV text
  • Tagged skills
  • Employer, industry and parent company
  • Job title

Candidates must fall within the salary band and radius, and have a CV. The top 40 candidates (set by Candidates read per run) go forward to AI scoring.

The AI reads the job description against each candidate's CV and work history, and returns:

  • A fit score
  • A summary
  • Reasons the candidate fits
  • Concerns
  • Similar employers
  • A competitor flag
 
The Final Score

The final score is a weighted mix of five components:

Component What it measures
AI fit The fit score returned by the AI.
Salary / rate How closely the candidate's salary or rate matches the job.
Distance How far the candidate is from the job.
Tagged skills Matching tagged skills. Only used if your database uses tagged skills.
Availability The candidate's availability against the job's start date.
  • If the job doesn't support a component (for example, it has no salary), that component drops out of the score.
  • If the AI couldn't score a candidate, they are ranked on the remaining components and flagged.
  • Select "How is the score worked out?" on the report for an explanation of the scoring.
 
Working With the Results
  • Tick candidates to add them straight to the Longlist or Shortlist.
  • Open the results as a saved search linked to the Requirement.
  • Each run shows its token usage on the report.
 
Report Parameters
Parameter Use
Weights Adjust how much each score component counts.
Radius The distance from the job within which candidates are included.
Tolerance How far outside the job's salary band a candidate can be.
Recency Limit results to more recently active candidates.
Use AI scoring Switch off to run a zero-cost version of the report without AI scoring.
Suggested Requirements and Suggested Contacts
 

These two options work the same way as Suggested Candidates but in reverse. They start from a Candidate record and find the jobs and people to put that candidate forward to. Both options are available on the Candidate record.

 
Comparison
  Suggested Requirements Suggested Contacts
Answers Which live jobs fit this candidate? Who should I spec this candidate to?
Matching uses Current and previous job titles, skills, type (Perm, Contract or Both), wanted rate or salary, and postcode. The same candidate criteria as Suggested Requirements.
Requirements searched Live requirements only, of a matching type. Perm candidates see Perm jobs, Contract candidates see Contract jobs, and Both sees either. Live and past requirements. Live requirements are weighted higher.
Results Requirements ranked best match first, with the score visible. The contacts on those requirements, each listed once.
Actions
  • Longlist or Shortlist the candidate to one or more jobs. The link shows on both the Candidate and Requirement records.
  • Create a Requirement search result from the suggestions.
  • Create a Contact search result linked to the candidate.
  • Use the search result to Spec CV the candidate to those contacts.
 
Changing the Criteria

On both options, you can change the job titles, skills, type, rate or salary, and location or distance, then run the suggestions again. If nothing fits, a "no suggestions found" message is shown.

Results respect each user's existing record security and visibility permissions.

AI Usage and Cost Controls
 

Each AI Suggestions run uses AI tokens. The following controls help manage usage:

  • Cached answers - AI answers are cached, so re-running an unchanged job costs nothing.
  • Usage log - Every AI call is logged with the user, requirement, tokens used and estimated cost.
  • Token caps - Monthly and per-run token caps are in place. When a cap is reached, new runs are blocked and the user is told why.
  • Zero-cost option - Switch off "Use AI scoring" to run Suggested Candidates without AI.
 
The AI Usage Screen

Go to Admin > System > AI Usage. The screen covers every AI feature in Colleague that logs usage, and shows:

  • Usage cards for this month and for a chosen period
  • A chart of tokens used by month
  • A grid you can export, broken down by month, user, feature and requirement