upload_contact_list_csv_audience

Upload a list of individual CONTACTS (people) as a Contact List CSV and create a CONTACT_LIST audience on the Metadata platform.

                ALSO KNOWN AS: "CSV Upload - Contacts", "Contacts List", "Contact List CSV", "CSV Contacts audience", "CSV Upload - Contacts List Audience".

                AUDIENCE TYPE: Contact List / CSV Upload - Contacts.
                This tool is ONLY for contact/people-level data (email, first name, last name, job title, etc.).
                Do NOT use this tool for company/account-level data (company names and websites) — use upload_account_list_csv_audience instead.

                This tool performs a two-step process:
                1. Generates a Contact List CSV file from the provided contact data and uploads it.
                2. Creates a CONTACT_LIST audience using the uploaded contact list file.

                WHEN TO USE:
                - "Create a CSV Upload - Contacts with the list"
                - "CSV Upload - Contacts"
                - "Create a contacts list audience"
                - "Upload these contacts as an audience"
                - "Create a contact list audience from these people"
                - "I have a list of emails and names, create an audience"
                - "Build a contact list audience"
                - "Upload contact list CSV"
                - When the data contains people-level fields: email, first name, last name, job title, company, country

                WHEN NOT TO USE:
                - When the user wants to upload company accounts (company name + website) — use upload_account_list_csv_audience.
                - When the data is account/company-level, not contact/people-level.

                WORKFLOW:
                1. Provide the audience name and an array of contact objects.
                2. The tool generates a CSV with the header: email,firstname,lastname,jobtitle,employeecompany,country,appleidfa,googleaid
                3. Uploads the CSV, then creates the CONTACT_LIST audience.

                ⚠️ CRITICAL — DATA MAPPING RULES (READ CAREFULLY BEFORE CALLING THIS TOOL):

                The "contacts" parameter is a JSON array of objects. Each object represents one contact/person
                and MUST use these exact field names:

                  - "email"             → The contact's email address (REQUIRED per contact)
                  - "firstname"         → The contact's first name
                  - "lastname"          → The contact's last name
                  - "jobtitle"          → The contact's job title / role
                  - "employeecompany"   → The company the contact works at
                  - "country"           → The contact's country
                  - "appleidfa"         → Apple IDFA (advertising identifier), optional
                  - "googleaid"         → Google Advertising ID, optional

                Example:
                  [
                    {
                      "email": "jane@metadata.io",
                      "firstname": "Jane",
                      "lastname": "Johnson",
                      "jobtitle": "Marketing Manager",
                      "employeecompany": "Metadata.io",
                      "country": "United States",
                      "appleidfa": "EA7583CD-A667-48BC-B806-42ECB2B48606",
                      "googleaid": ""
                    },
                    {
                      "email": "john@metadata.io",
                      "firstname": "John",
                      "lastname": "Johnson",
                      "jobtitle": "Marketing Manager",
                      "employeecompany": "Metadata.io",
                      "country": "United States",
                      "appleidfa": "",
                      "googleaid": "cdda802e-fb9c-47ad-9866-0794d394c912"
                    }
                  ]

                IF THE USER PROVIDES A FILE (CSV, XLSX, spreadsheet, or any tabular data):
                  1. You MUST first read and inspect the file contents.
                  2. Identify which columns map to: email, firstname, lastname, jobtitle, employeecompany, country, appleidfa, googleaid.
                     - The columns may NOT be literally named as above. They could be named:
                       "Email Address", "E-mail", "First Name", "First", "Last Name", "Surname",
                       "Job Title", "Title", "Role", "Position", "Company", "Organization", "Employer",
                       "Country", "Location", "Apple IDFA", "IDFA", "Google AID", "GAID", or any variation.
                     - Use your best judgment to map the correct columns to the expected field names.
                     - If ambiguous, ask the user to clarify which column maps to which field.
                  3. Extract every row from the file and build the contacts array yourself,
                     mapping each column value to the correct field name.
                  4. Do NOT pass raw file contents, column headers, or file paths — always transform into
                     the array-of-objects format described above.
                  5. Skip rows where email is empty/missing (email is the minimum required field per contact).
                  6. For any field not present in the source data, omit it or pass an empty string.
                  7. If the file has no identifiable email column, ask the user which column contains emails.

                DO NOT:
                  - Use the source file's column names as field names — always normalize to: email, firstname, lastname, jobtitle, employeecompany, country, appleidfa, googleaid.
                  - Send the raw file path or file bytes — extract the data and build the array.
                  - Confuse this with account/company uploads — this is for PEOPLE, not companies.

                TWO WAYS TO SUPPLY THE CONTACTS — provide EXACTLY ONE of:
                  • `contacts`: an inline JSON array of contact objects. Use this for short ad-hoc lists you have already parsed into context.
                  • `contacts_source_csv_url`: a public URL of a CSV file with header EXACTLY `email,firstname,lastname,jobtitle,employeecompany,country,appleidfa,googleaid` (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 + uploads the file without the rows ever travelling through your LLM context (essential for 100k+ row contact files).
                If both are provided, or neither, the tool errors with a clear message — pick one.

                CSV-URL HEADER RULES (when you choose the `contacts_source_csv_url` path):
                  - First row of the CSV MUST be exactly `email,firstname,lastname,jobtitle,employeecompany,country,appleidfa,googleaid` (case-insensitive).
                  - Rows with an empty email are dropped server-side before counting.
                  - The 300–300,000 row limit is enforced on the post-filter count.
                  - The server enforces a 50 MB cap on the downloaded file.

                PARAMETERS:
                - audience_name: Name for the new contact list audience (required)
                - contacts: Array of contact objects (optional, mutually exclusive with contacts_source_csv_url).
                  At minimum each contact must have "email". All other fields are optional but recommended.
                - contacts_source_csv_url: URL of a contacts CSV with the canonical 8-column header (optional, mutually exclusive with contacts).

                RETURNS:
                - success: Whether the operation completed successfully
                - audience_name: The name of the created audience
                - audience_type: CONTACT_LIST
                - file_id: The ID of the uploaded contact list file
                - contacts_count: Number of contacts processed by the backend
                - contacts_provided: Number of contacts sent in the request

                IMPORTANT NOTES:
                - CONTACT LIMITS: Minimum 300 contacts, maximum 300,000 contacts.
                - Email is the minimum required field per contact — contacts without email are dropped.
                - The audience type created is CONTACT_LIST, distinct from Account List CSV (FIRMOGRAPHIC_INCLUDE).
                - appleidfa and googleaid are optional mobile advertising identifiers — leave empty if not available.