> ## Documentation Index
> Fetch the complete documentation index at: https://heybtw.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# import_people

> Bring people from your CRM or a prospect file into heyBTW so they can be saved as a List.

> [!WARNING]
>
> Writes to your heyBTW workspace. On `confirm` (or a call with no `action`) it creates person records. It never saves a List, never sends an invite and never enriches anyone. Preview first.

Your audience often lives in a CRM, not in past event sign-ups. import\_people brings those people into heyBTW by email so [save\_list](https://heybtw.com/docs/tools/save-list.md) can keep them as a List and [activate\_list](https://heybtw.com/docs/tools/activate-list.md) can invite them.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Take the 40 VPs I just pulled from HubSpot and get them ready to invite to the LA dinner."
* "Import this Sales Navigator export with each person's city."
* "Load my CRM list in chunks, then save it as a List."
* "Mark which of these my teammate Tony already knows."

Imported people are not sign-ups or attendees. They appear in no roster, funnel or attribution count. For a file of event attendees, use [record\_signups](https://heybtw.com/docs/tools/record-signups.md) or [create\_import\_link](https://heybtw.com/docs/tools/create-import-link.md) instead.

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `people` | list of objects | On preview, append and one-call import | 1 to 500 entries. Each takes `email` (required), and optionally `name`, `company`, `title`, `external_id`, `location` (an object with `city`, required, and optional `region` and `country`), `known_by` (up to 5 workspace member emails). No other key is accepted. Never pass on confirm. |
| `action` | string | No | `preview`, `append` or `confirm`. Omitted, the call imports its people at once. |
| `client_request_id` | string | Yes | A fresh hyphenated UUID per call (per chunk). The same id replays the committed result. |
| `import_token` | string | On append and confirm | From the preview. Valid 15 minutes after the preview or the last append. |
| `source_system` | string | When any person has `external_id` | `attio`, `hubspot`, `salesforce` or `other`. Name it again on an append whose people carry an external\_id. |
| `source` | string | No | `crm_list` when the people are the members of a CRM list for a past event (invited). |
| `source_ref` | object | With `source: crm_list` | The list: `crm`, `object`, `id`, optional `name`, and `member_created_range`. |
| `check_token` | string | Instead of `people` | check\_people's `data[0].check_token`. The rows it selects are imported as if sent. Never send both, and never on a confirm. |
| `check_rows` | string or integer\[] | With `check_token` | `matched`, `unmatched`, `all`, or a list of the check's `row` values. `data[0].check_rows` names each person's row in that check, so join on `row`. |
| `contract_version` | string | No | Omit for v1, the only advertised version. |

`location` is where the person is, as the source states it. Never pass a company address and never coordinates. The city is stored as stated and never geocoded.

## Workflow

**1. Preview the first chunk**

Call `action: "preview"` with up to about 50 people and a fresh `client_request_id`. Nothing is imported. Read `row_outcomes`, `workspace_overlap` and `company_carry`.

**2. Tell the user what the preview found**

Relay `workspace_overlap.sentence` and `company_carry.sentence` as written. Offer each `candidates_by_name` entry for the user to confirm. Never call two emails the same person on your own. Name any `suspect_rows`.

**3. Append the rest**

For more people, call `action: "append"` with the `import_token`, the next chunk and a fresh `client_request_id`. Report the `staged` totals, never one chunk's. At most 2,000 people staged in all.

**4. Confirm once**

After the user agrees, call `action: "confirm"` with the `import_token`, a fresh `client_request_id` and no `people`. It imports every staged person once.

**5. Save the List**

Pass `data[0].member_emails` to [save\_list](https://heybtw.com/docs/tools/save-list.md) unchanged.

On a transport error, retry with the same `client_request_id`. A committed import is replayed (`idempotent_replay: true`), never repeated.

## Response

Per person, by email (case-insensitive): someone the workspace already holds is merged (nothing overwritten), an erased person is rejected and stays erased, a malformed address is rejected, anyone else is created.

| Field | Meaning |
| - | - |
| `action`, `imported` | Which step ran, and whether anything was written. A preview reads `imported: false`. |
| `created_count`, `merged_count`, `rejected_count` | What the confirm would do (preview) or did. |
| `row_outcomes` | One outcome per person sent, in order: `created`, `merged`, `duplicate`, `rejected_invalid_email`, `rejected_erased`. |
| `import_token`, `expires_at` | The staging token and when it lapses. |
| `suspect_rows`, `suspect_count`, `suspect_by_kind` | Rows that may not be a person (spreadsheet\_error, notetaker\_bot, resource\_address, role\_address, plus\_addressed, company\_list). |
| `workspace_overlap` | How many of these people the workspace already knew and where, with `sentence` to relay and `candidates_by_name`. |
| `company_carry` | How many rows carry company, title or LinkedIn, with `sentence` to relay. |
| `member_emails` | On confirm: every person now resolvable (created plus merged). Pass to save\_list. |
| `limited_match_count`, `location_count`, `known_by_count`, `known_by_rejected_count` | On confirm: personal addresses with no company, locations recorded, known\_by facts recorded and refused. |
| `source`, `source_ref`, `import_gaps` | For a CRM list import: the list, and what the import does not bring with the tool that fills it. |

This sample is trimmed from a real preview of fictional example.org people sent today. Nothing was imported.

```json theme={null}
{
  "tool": "import_people",
  "data": [
    {
      "action": "preview",
      "imported": false,
      "idempotent_replay": false,
      "created_count": 2,
      "merged_count": 0,
      "rejected_count": 1,
      "row_outcomes": ["created", "created", "rejected_invalid_email"],
      "import_token": "O9fON8WZFt-aPZcm-vvbpVZAIofbpKF8ul3UR7QG-os",
      "expires_at": "2026-11-03T19:52:24.543Z",
      "suspect_rows": [],
      "suspect_count": 0,
      "workspace_overlap": {
        "people": 2,
        "candidates_by_name": [
          {
            "row": 1,
            "email": "sam.okafor@example.org",
            "name": "Sam Okafor",
            "existing_email": "sam.okafor@guides-test-c.example.com",
            "existing_name": "Sam Okafor",
            "existing_source": "collab"
          }
        ],
        "candidates_by_name_count": 1,
        "sentence": "None of these 2 people are in this workspace by email, but 1 may be the same person under another email (listed, not merged)."
      },
      "company_carry": {
        "rows": 2,
        "rows_carrying_company_title_or_linkedin": 2,
        "sentence": "2 of 2 rows carry company, title or LinkedIn."
      }
    }
  ],
  "status": "partial"
}
```

## Rules the agent must follow

* Preview first, show the user, and confirm only after they agree.
* Relay `workspace_overlap.sentence` and `company_carry.sentence` as written.
* Never merge two emails as one person without the user's confirmation.
* Leave a suspect row out of save\_list only if the user agrees. Never exclude anyone on your own.
* Never treat an import as evidence that anyone registered or attended.
* Never pass a company's address as a person's `location`.

## Errors and gaps

* Rejected rows are disclosed in `gaps`. Correct a malformed address and send it in a later `append`. Do not re-import an erased person.

* `invalid_parameter`: a person carries a key this tool does not accept, `people` is empty or over 500, `source_system` is missing beside an `external_id`, or a chunk was sent again under a new `client_request_id`.

* `insufficient_scope`: the OAuth token lacks `mcp:tools:write`. Nothing is imported.

* Writing needs no plan: every workspace can write.

* `internal_error`: retry once with the same `client_request_id`.

## Related

* [save\_list](https://heybtw.com/docs/tools/save-list.md): keep the imported people as a List.
* [check\_people](https://heybtw.com/docs/tools/check-people.md): see what the workspace already knows before importing.
* [activate\_list](https://heybtw.com/docs/tools/activate-list.md): invite the List.
* Playbook: [Fill the room in the two weeks before](https://heybtw.com/docs/playbooks/invite-sprint.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.