Reference

Expand job titles

expand_job_titles: Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to.

Generated from the contractsView as Markdown

Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to. Use it before counting so the user can see and edit which titles a keyword covers; nothing is expanded silently. Free and needs no account. Put the returned filter into the audience, then call count_audience. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Property	Value
Tool name	`expand_job_titles`
Position in tools/list	5 of 22
Cost	Free
Scope	None. Works without an account.
Annotations	readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Kind	Read only; idempotent, not destructive, closed world
REST equivalent	`POST /v1/job-titles/expand`

Input

The schema sets additionalProperties to false, so a member that is not listed is refused.

Member	Type	Required	Description
`terms`	array of string	no	Title keywords to expand, such as marketing manager.
`bundle`	enum: `sdm`, `manager_and_above`, `owner_managed`	no	A title bundle to show: sdm, manager_and_above or owner_managed.
`mode`	enum: `contains`, `starts_with`, `exact`	no	contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.
`expand`	array of enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations`	no	Expansion sets to apply, each once. Left out, the four default sets apply.
`dataset`	enum: `uk_contacts`, `ie_contacts`, `global_contacts`	no	The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.

Example call

The params of a tools/call request:

{
  "name": "expand_job_titles",
  "arguments": {
    "terms": ["marketing manager"],
    "mode": "contains"
  }
}

Output

The result carries structuredContent that matches this schema, and one line of text that leads with the number.

Member	Type	Always present	Description
`dataset_version`	string	yes	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`mode`	enum: `contains`, `starts_with`, `exact`	yes	contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion.
`expand`	array of enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations`	yes
`terms`	array of `ExpandedTerm`	yes
`terms[].term`	string	yes	A matched title.
`terms[].from_term`	string	yes	The input term it came from.
`terms[].expansion_set`	enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations` or `input`	yes	The expansion set that produced it, or input for the term itself.
`terms[].contacts`	integer (0 or more) or `under 10` or `suppressed`	yes	A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.
`terms[].excluded`	boolean	no	True when exclude_terms removed it from the audience.
`total_contacts`	integer (0 or more) or `under 10` or `suppressed`	yes	A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.
`bundle`	object or null	yes
`bundle.id`	enum: `sdm`, `manager_and_above`, `owner_managed`	yes
`bundle.label`	string	yes
`bundle.status`	enum: `confirmed`, `proposed`, `to_confirm`	yes
`bundle.resolves_to`	`WhereNode`	yes	A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles.
`filter`	`Filter` or null	yes	A ready matches filter for the terms, or null for a bundle.
`disclosure`	`Disclosure`	yes	Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers.
`disclosure.level`	enum: `exact`, `rounded`	yes	exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.
`disclosure.rounded_to`	integer or null	yes	5 when numbers are rounded; null when they are exact.
`disclosure.secondary_suppression`	boolean	yes	True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced.
`disclosure.notes`	array of string	yes

Errors

A failed call returns isError true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with code, detail, next_step and did_you_mean. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See Errors.