ACTION_ID: merge_employee_finder_structured_array
NAME: Merge Employee Lists
CATEGORY: transform
CREDITS: 0

Merge multiple employee structured arrays into a single list. Combines
results from different employee finder sources into one unified
contact list.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

lists_of_employees (type: structured_array, required)
  The employee structured arrays to combine, from different employee
  finder actions. Each entry must be a structured_array of people
  data (the output format of an employee finder), not a raw_array.
  The action accepts one or more structured_array references; pass
  each upstream employee finder's output as a separate entry in the
  lists array (see HOW TO CONFIGURE below).

================================================================================
2. OUTPUTS
================================================================================

no_of_employees (type: number) — No. of Employees
  Total number of employees in the merged list.

list_of_employees (type: structured_array) — List of Employees
  All selected structured arrays combined into a single
  structured_array. Per-row fields:
  - first_name (type: string) — First Name
  - last_name (type: string) — Last Name
  - linkedin_url (type: url) — LinkedIn URL
  - title (type: string) — Title
  - headline (type: string) — Headline
  - summary (type: string) — Summary
  - profile_picture (type: imageUrl) — Profile Picture
  - location (type: string) — Location
  - twitter_url (type: url) — Twitter URL
  - facebook_url (type: url) — Facebook URL
  - github_url (type: url) — Github URL
  - experience (type: jsonArray) — Experience
  - education (type: jsonArray) — Education
  - skills (type: array) — Skills
  - languages (type: array) — Languages
  - number_of_connections (type: number) — Number of Connections
  - patents (type: jsonArray) — Patents
  - awards (type: jsonArray) — Awards
  - courses (type: jsonArray) — Courses
  - certifications (type: jsonArray) — Certifications
  - projects (type: jsonArray) — Projects
  - publications (type: jsonArray) — Publications
  - volunteer_experiences (type: jsonArray) — Volunteer Experiences
  - recommendations (type: jsonArray) — Recommendations
  - email (type: email) — Email
  - current_organization_name (type: string) — Current Organization Name
  - current_organization_linkedin (type: url) — Current Organization Linkedin

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body:

{
  "inputs": {
    "lists_of_employees": [
      "{{get_employees_by_company_using_apollo_1.list_of_employees}}",
      "{{get_employees_by_company_using_sales_navigator_1.list_of_employees}}"
    ]
  }
}

Pass each upstream employee finder's `list_of_employees` output as
an entry in `lists_of_employees`. Any number of structured arrays
may be combined.

================================================================================
4. KEY NOTES
================================================================================

- Only works with employee structured arrays (output from employee finder
  actions). Doesn't work with csv_to_structured_array_format output or other
  list types.
- Pair with `push_data_to_sheet` after merging to expand the
  combined list into individual rows.
- Free to run.
- Merge concatenates; it does NOT deduplicate. The same person
  surfaced by multiple finders (e.g. Apollo + Floqer Native both
  return the company's CPO) appears once per finder in the merged
  list. Dedupe downstream on the destination sheet by adding
  `auto_dedupe_rows` keyed on `linkedin_url` immediately after
  the `push_data_to_sheet` step. Use
  `select_dedupe_action: "delete_duplicate"` for a clean roster,
  or `"mark_as_duplicate"` if you want to keep duplicates for
  audit and filter them out before the next paid step. See
  https://floqer.com/docs/action-detail/auto_dedupe_rows.txt.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Sits between employee finder actions and push_data_to_sheet —
combine results before expansion.

Pattern: get_employees_by_company_using_apollo +
get_employees_by_company_using_sales_navigator (in parallel) ->
merge_employee_finder_structured_array -> push_data_to_sheet ->
enrich_person_linkedin_profile -> person_work_email_waterfall ->
outreach.

================================================================================
6. WHEN TO USE
================================================================================

Use merge_employee_finder_structured_array when you ran multiple employee finder actions and
want to combine the results into one list before expanding to
individual rows.

  - Combine multiple employee finder structured_array outputs.
  - Consolidate before enrichment. Merge all found contacts into a
    single list, then run enrichment once.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need to merge non-employee lists (CSV-to-list output, arbitrary data)
  -> use llm_models or format_data_using_js_expression for custom
     merging
     (https://floqer.com/docs/action-detail/<action_id>.txt)

One of your inputs is a `raw_to_structured_array` output
  -> this action will NOT ingest it. The merge action recognises
     the structured-array shapes produced by the dedicated employee
     finders (Apollo `list_of_employees`, Sales Nav, Floqer Native
     `employees`) — those have known column schemas it can map onto
     its unified output. A `raw_to_structured_array` output is a
     valid structured_array but its columns are discovered, not
     declared, so the merge action can't reconcile them with the
     finder schemas and won't include those rows in the result.
     This trips up the natural pattern of `llm_web_agents`
     (people-search via raw_array) -> `raw_to_structured_array`
     -> `merge_employee_finder_structured_array` with a dedicated
     finder.
     Workaround: skip the merge step. Run two separate
     `push_data_to_sheet` actions into the same destination sheet
     (one fed by the finder's structured_array, one fed by the
     raw_to_structured_array output), then dedupe on the
     destination sheet via `auto_dedupe_rows` keyed on a normalised
     LinkedIn URL. Tag the source on each push (e.g. a literal
     `"floqer_native"` / `"web_agent"` value on a `source` column)
     so the destination rows are traceable back to which finder
     surfaced each person.

================================================================================

This file is maintained manually. Last updated: 2026-05-08.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt