> ## 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.

# check_people

> What this workspace already knows about each person on a list you pulled elsewhere.

> [!NOTE]
>
> Read-only.

> [!NOTE]
>
> This tool is evolving. This page describes what the connector serves today and will be revised as the tool changes.

You have a list from somewhere else (a prospect file, a CRM export, a spreadsheet). check\_people tells you, per email, whether this workspace has seen the person before: events attended, invites recorded, and which teammates know them. Call it before importing or inviting a list.

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

## When to use it

* "Who on this list has been to one of our events?"
* "Have we invited any of these people before, and did they come?"
* "Does anyone on the team know these people?"
* "Before I import this list, what do we already have on them?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `people` | list of objects | Yes | 1 to 500 entries of {`email`, `company_domain`, `name`}. Only `email` is read. Any other key is refused. |
| `channel_id` | string | No | A collab from [list\_events](https://heybtw.com/docs/tools/list-events.md). Measures `event_history.this_city` against that event's city. |
| `event_name` | string | No | Instead of `channel_id`. An ambiguous name returns no rows and lists the candidates. |
| `fields` | list of strings | No | Any of `identity`, `event_history`, `invite_history`, `known_by`, `target_spec_match`. Omit for all. |
| `contract_version` | string | No | Omit for v1, the only advertised version. |

Send a longer list in chunks of 500. Do not send the same chunk twice.

## Response

`crm_context` comes first. `data[0]` holds one row per person sent, in input order.

| Field | Meaning |
| - | - |
| `rows[].row` | The position in the list you sent. |
| `rows[].identity` | `matched` when the workspace holds an attended event, a recorded invite or an imported contact for the email, else `unmatched`. |
| `rows[].event_history` | {`attended_count`, `last_at`, `last_collab`, `this_city`}. `this_city` is null without a collab or a resolvable city. |
| `rows[].invite_history` | {`count`, `last_at`, `last_channel`, `last_outcome`}: `registered`, `attended` or `none`. |
| `rows[].known_by` | Emails of workspace members who know the person. |
| `rows[].target_spec_match` | Null on every row in this version. |
| `rows[].row_gaps` | For example `invalid_email`. One bad row never fails the call. |
| `counts` | `matched`, `unmatched`, `seen_before`, `invited_before`, `no_history`, over the served rows. |
| `carry` | The CRM check to run in your own connector, joined on `email` and `company_domain`. |
| `target_spec` | Whether a target spec is saved, with the next step when not. |

This sample is trimmed from a real call today on fictional fixture people.

```json theme={null}
{
  "tool": "check_people",
  "data": [
    {
      "rows": [
        {
          "row": 0,
          "email": "luis.castillo@wavecrestgames.com",
          "company_domain": "wavecrestgames.com",
          "identity": "matched",
          "event_history": {
            "attended_count": 1,
            "last_at": "2026-11-19T02:30:00.000Z",
            "last_collab": "ScaleUp.ai x Marlowe Cloud: LA Revenue Leaders Dinner",
            "this_city": null
          },
          "invite_history": {
            "count": 1,
            "last_at": "2026-10-13T16:30:00.000Z",
            "last_channel": "personal_email",
            "last_outcome": "registered"
          },
          "known_by": ["ben@heybtw.com"],
          "target_spec_match": null
        },
        {
          "row": 1,
          "email": null,
          "company_domain": null,
          "row_gaps": ["invalid_email"]
        }
      ],
      "counts": { "matched": 1, "unmatched": 0, "seen_before": 1, "invited_before": 1, "no_history": 0 },
      "rows_served": 2,
      "rows_checked": 2,
      "carry": {
        "destination": "crm",
        "via": "your_tools",
        "join_keys": ["email", "company_domain"],
        "ask": "which of these are customers or have open deals, and who owns them"
      }
    }
  ],
  "status": "ok"
}
```

## Rules the agent must follow

* These are facts, never a verdict. Do not suppress, skip, tier or rank anyone from them.
* Null or absent is unknown, never zero.
* Never report a person with no CRM value as net-new. Run the `carry` check in the user's own CRM connector.
* Never recompute these facts from get\_event\_details calls.

## Errors and gaps

* `invalid_parameter`: `people` missing, empty or over 500, an entry with a key this tool does not read, a malformed `channel_id`, or an unknown name in `fields`.
* `entity_not_found`: no event with that `channel_id` or `event_name`.
* A response trimmed to fit says so in a gap and in `next_row`. Counts cover the served rows only. Narrow with `fields`.
* `internal_error`: retry once.

## Related

* [import\_people](https://heybtw.com/docs/tools/import-people.md): bring the unmatched people in.
* [get\_invite\_recommendations](https://heybtw.com/docs/tools/get-invite-recommendations.md): the same person facts, for candidates heyBTW finds.
* [save\_target\_spec](https://heybtw.com/docs/tools/save-target-spec.md): save who belongs in the room.
* 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.