Skip to main content
Read-only.
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.

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

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

Send the file as it is

With csv, each data row of the file is a row, in file order, with its file line. A row with no email, or a line with the wrong number of cells, is served in place with row_gaps (missing_email or malformed_row): one bad row never fails the call. company_domain is read from a column headed company_domain, domain, website or company website. data[0].column_map lists each column, what it was read as and why. With format: "csv" the answer holds your columns as sent, then heyBTW’s: row, known_by, last_event, last_event_status (attended or registered), partner, invite_count, personalization and row_gaps, in data[0].columns order. A heyBTW column your file already names is prefixed heybtw_.

More facts per row

Beside identity, event history, invite history and known_by, each row can carry: account and partner_overlap are null when the row has no company_domain.

Check once, then import or save

data[0].check_token holds the rows this response served for 15 minutes (check_token_expires_at). To import or save them, pass it to import_people or save_list with check_rows (matched, unmatched, all, or a list of row values). Never send the same people again. A response trimmed to fit says so in a gap and in data[0].next_row, and its counts cover the served rows only. Rows keep their position in your list, so join on row. As a guide, about 140 people fit with no fields named, about 370 with fields set to identity and invite_history, and all 500 with format: "csv".

Response

crm_context comes first. data[0] holds one row per person sent, in input order. This sample is trimmed from a real call today on fictional fixture people.

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.