Upload a list of company ACCOUNTS (website, plus an optional name) as an Account List CSV and create a FIRMOGRAPHIC_INCLUDE audience on the Metadata platform, optionally overlaid with platform-side contacts criteria.
AUDIENCE TYPE: Account List CSV / CSV Upload - Accounts (platform stores `customAudienceType=FIRMOGRAPHIC_INCLUDE`; the main UI's audience-map renders this enum as "CSV Upload - Accounts").
This tool is ONLY for company/account-level data (company names and websites).
Do NOT use this tool for contact-level data (emails, phone numbers, individual people).
For contacts, use upload_contact_list_csv_audience instead.
TWO WAYS TO SUPPLY THE ACCOUNT LIST — provide EXACTLY ONE of:
• `companies`: an inline JSON object map `{ "<companyname>": "<companywebsite>", ... }`. Use this for short ad-hoc lists you have already parsed into context.
• `companies_source_csv_url`: a public URL of a CSV file with header EXACTLY `companyname,companywebsite` (case-insensitive, whitespace-trimmed). Use this WHENEVER THE USER ATTACHED A CSV to the chat — the URL is surfaced to you via `AudienceBrief.attached_file_urls`; pass it through verbatim. The MCP server downloads + validates + parses the CSV so a multi-megabyte file never has to travel through your context.
If both are provided, or neither, the tool errors with a clear message — pick one.
OPTIONAL CONTACTS CRITERIA: layer per-contact filters on top of the account list, matching the same shape `create_firmographic_audience` uses:
• `location_country_ids` / `location_state_ids` — geography
• `job_title_includes` / `job_title_excludes` — free-text title keywords
• `job_function_include_ids` / `job_function_exclude_ids`
• `seniority_include_ids` / `seniority_exclude_ids`
• `contacts_per_company_limit`
When set, the resulting audience matches only contacts inside the listed companies that ALSO satisfy these filters — e.g. "this 1,999-account list, but only VP/Director/Manager Engineering contacts in Canada + Saint Pierre and Miquelon + United States" becomes a single call. When all of these are omitted, every contact in every uploaded company is matched.
WHEN TO USE:
- "Upload these companies/accounts as an audience" / "Create an account list audience" / "Upload account list CSV"
- "Create a CSV Upload - Accounts audience with this CSV and these contact filters"
- The user attached a CSV of companies (website, with or without a name) and asked for a CSV-Upload audience
WHEN NOT TO USE:
- When the data is contact-level (emails, phone numbers, individual people) — use `upload_contact_list_csv_audience`.
- For pure firmographic targeting without an attached account list — use `create_firmographic_audience`.
INLINE-MAP DATA MAPPING RULES (when you choose the `companies` path):
- Each KEY must be the **company name**; each VALUE must be the **company website URL**.
- Format: { "<companyname>": "<companywebsite>", ... }
- Example:
{
"Acme Corp": "https://acme.com",
"Globex International": "https://globex.com",
"Salesforce": "https://salesforce.com"
}
- DO NOT pass column headers as keys; DO NOT reverse the mapping; DO NOT send raw file paths or bytes.
CSV-URL HEADER RULES (when you choose the `companies_source_csv_url` path):
- The first row of the CSV MUST be exactly `companyname,companywebsite` (case-insensitive — `Company Name,Website` is rejected; rename the columns first or fall back to the inline map path).
- Only `companywebsite` must be filled: the platform matches accounts on the website domain and treats `companyname` as optional, so a file whose name column is empty on every row is a valid account list. Never ask the user to fill in company names.
- Rows with an empty company website are dropped server-side.
- The server enforces a 50 MB cap on the downloaded file.
PARAMETERS:
- audience_name (required)
- companies (optional, mutually exclusive with companies_source_csv_url)
- companies_source_csv_url (optional, mutually exclusive with companies)
- location_country_ids / location_state_ids (optional contacts criteria)
- job_title_includes / job_title_excludes (optional)
- job_function_include_ids / job_function_exclude_ids (optional)
- seniority_include_ids / seniority_exclude_ids (optional)
- contacts_per_company_limit (optional)
RETURNS:
- success, id / audience_id, audience_name, audience_type (FIRMOGRAPHIC_INCLUDE), file_id, companies_count, upload_filename, expectedNumberOfCompanies, expectedNumberOfContacts, cappedContactCount
- companies_count: the rows sent, each with a website. dropped_without_website names up to 25 rows left out for having none, which the platform cannot match; dropped_without_website_count counts them all.
- companies_summary: status is matching, because the platform matches the list after this call returns, and submitted_companies is how many rows the platform took in. Read the final count later with get_deep_audience_details, and never report companies_count or expectedNumberOfCompanies as the audience's final size.
IMPORTANT NOTES:
- There is a small delay between upload and audience creation while the platform processes the file; the tool waits for that internally.
- The companies map / source CSV must contain at least one row with a company website.
- Company websites should be valid URLs (e.g., https://example.com).
