Create a new target group with name and targeting criteria. Supports BOTH include AND exclude rules — including excluding existing Metadata audiences.
PREREQUISITE: All criteria IDs MUST come from search_target_group_criteria. estimate_target_group first is MANDATORY: verify isMatchCountTooSmall=false and report the reach to the user BEFORE creating. A target group created without an estimate can land at zero matches and nothing downstream will notice (PRD-31759). Same bar as update_target_group.
USE FOR: "create target group named X with criteria Y", "save this target group as X", "create new audience called X", "create target group excluding companies Z", "create target group that excludes audience X".
WARNING: CHANNEL: This tool creates LINKEDIN target groups only. Do NOT infer channel from the underlying audience NAMES (e.g. an audience called "Reddit Conquest Mktg LI_n7q" does NOT mean the user wants a REDDIT target group — audience naming is human convention, not a routing signal). Use REDDIT only when the user explicitly named the REDDIT channel in the request; in that case use `create_reddit_target_group` instead. When in doubt, ask the user which channel.
**CRITICAL FOR LINKEDIN**: LOCATION must be FIRST criteria in include array with isModifiable=false.
TARGETING STRUCTURE (full example with include + exclude criteria + exclude audiences):
{
"include": [
{
"isModifiable": false,
"criteria": [{"type": "NATIVE_LOCATION", "data": [
{"externalId": "urn:li:geo:101165590", "name": "United Kingdom"},
{"externalId": "urn:li:geo:103644278", "name": "United States"}
]}],
"audiences": []
},
{
"isModifiable": true,
"criteria": [{"type": "AGE", "data": [{"externalId": "urn:li:ageRange:(25,34)", "name": "25 to 34"}]}],
"audiences": []
}
],
"exclude": {
"isModifiable": true,
"criteria": [
{"type": "COMPANY_NAME", "data": [{"externalId": "urn:li:organization:1090", "name": "Philips"}]}
],
"audiences": [
{
"mdAudienceId": 45316,
"name": "ICP Pharma LifeSci Leaders",
"type": "FIRMOGRAPHIC_EXCLUDE",
"matchCount": 213127,
"matchCountType": "FIXED_SIZE",
"inactive": false,
"criteria": [{"type": "NATIVE_LOCATION", "data": [{"externalId": "urn:li:geo:103644278", "name": "United States"}]}]
}
]
}
}
INCLUDE: Array of rule blocks (AND-joined). Each block holds a criteria group.
EXCLUDE: Single object (NOT array) with `criteria` and `audiences`. Anything matching exclude is removed.
WARNING: AUDIENCES ≠ TARGET GROUPS. Both `include[].audiences` and `exclude.audiences` accept Custom Audience records ONLY (the entities returned by `get_matched_audiences`). Target Groups (the entities returned by `list_target_groups` / `retrieve_target_group_by_id`) are a separate entity in a separate ID space and CANNOT be attached here; the platform silently drops or rejects them. If the user names "X" and only `list_target_groups` matches it (not `get_matched_audiences`), do NOT pass the Target Group's id as `mdAudienceId`. Stop, tell the user "X is a Target Group, not a Custom Audience", and offer to rebuild X as a Custom Audience (e.g. via `create_audiences` with the same criteria) before retrying.
INCLUDE AUDIENCES: `include[].audiences` accepts ANY Metadata audience type — there is NO allow-list and NO restriction to specific types. The audience must be live on the channel, though: a row with inactive=true (LinkedIn segment archived, failed or still building) is refused by the platform and sized at 0, so pick an active row. Pass any audience returned by the audience listing tools (e.g. FIRMOGRAPHIC_INCLUDE, FIRMOGRAPHIC_INCLUDE_SFDC, NATIVE_LINKEDIN, NATIVE_FACEBOOK, RETARGETING, TECHNOGRAPHIC, SFDC_ACCOUNT_DYNAMIC, MA_CONTACTS_DYNAMIC, CONTACT_LIST, and any other type, including types not enumerated in any tool schema). Type-name enums seen in the audience tool schemas describe how audiences are CLASSIFIED, not which can be attached here. Caveat: estimates may under-report (or return zero) when combining server-resolved audiences (e.g. SFDC dynamic, retargeting) with native LinkedIn criteria — that is an estimate-side reconciliation issue, not a creation constraint, so a zero estimate does not necessarily mean the platform will reject the create call. If a zero estimate is suspected to be a reconciliation artifact, attempt the create and verify in the UI.
HOW TO EXCLUDE AN EXISTING METADATA CUSTOM AUDIENCE: Add it as an object in `exclude.audiences`. The tool pre-flight-rejects placeholder values — never invent ids or types when you don't know them, call `get_matched_audiences` first and use the real values from the response. Required fields:
- `mdAudienceId` (integer, REQUIRED): The numeric Custom Audience ID from `get_matched_audiences`, its `customAudienceId` / `mdAudienceId` field (e.g. 49067, 45316), NEVER that row's `id` (the channel row id). NEVER the audience name string, NEVER a placeholder like 1/2/3/4 (real Custom Audience IDs are 5-digit numbers; the tool rejects anything under 100), and NEVER a Target Group id (those come from `list_target_groups`; see the AUDIENCES ≠ TARGET GROUPS note above).
- `name` (string): Audience name.
- `type` (string): MUST be the EXCLUDE variant of the audience type, e.g. `FIRMOGRAPHIC_EXCLUDE`, `RETARGETING_EXCLUDE`, `CONTACT_LIST_EXCLUDE`. NEVER the placeholder string "AUDIENCE" — the tool rejects that pre-flight.
- `matchCount` (int), `matchCountType` ("FIXED_SIZE"), `inactive` (bool): copy from audience record. The tool pre-flight-rejects entries with `inactive: true` (an audience still matching after creation cannot be attached yet — attach it once it is active).
- `criteria`: The audience's own criteria array (copy from the audience's definition).
CRITERIA TYPES (all IDs from search_target_group_criteria), valid in BOTH include and exclude:
- NATIVE_LOCATION / LOCATION: location data — MANDATORY FIRST in include. Multi-country geo goes in ONE location criterion with one {externalId, name} entry per country (e.g. "Canada and USA" = 2 entries in the same data array). Never silently drop a country the user named.
- AGE, COMPANY_CATEGORY, COMPANY_GROWTH_RATE, INDUSTRY, COMPANY_NAME, REVENUE, EMPLOYEE: Array of {externalId, name}
- JOB_FUNCTION, JOB_TITLE, MEMBER_GROUP, MEMBER_INTEREST, MEMBER_SKILL, MEMBER_BEHAVIOR, SENIORITY, FOLLOWED_COMPANIES: Array of {externalId, name}
- YEARS_OF_EXPERIENCE_RANGE: {"min": 4, "max": 5}
WORKFLOW: search_target_group_criteria → build targeting (include + optional exclude criteria/audiences) → estimate_target_group → confirm → create_target_group
RESPONSE: {id, name, channel, audienceSize, status, createdDate, targeting}
