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

# create_import_link

> Get a short-lived, single-use link the user opens to drop a guest export file into heyBTW's attendee importer.

> [!WARNING]
>
> Writes to your heyBTW workspace: it issues one single-use import link for one of your collabs. The link itself imports nothing until the user drops a file and confirms in heyBTW. It sends nothing and never writes to the event platform.

No rows pass through the conversation. Reach for it instead of record\_signups when the export has more than about 50 rows or any custom registration question columns: sending every row through the conversation is the slowest part of an import, and record\_signups does not record question columns, which the importer keeps.

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

## When to use it

* "I have the Eventbrite export, 400 rows. Get it in."
* "The guest list has our custom questions, keep those."
* "Give me a link so I can upload the CSV myself."

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `channel_id` | string | Yes | The collab, from list\_events or create\_collab. |
| `contract_version` | string | No | Omit for v1, the only version advertised. |

Nothing else is sent. Never pass the file or its rows.

## Workflow

**1. Make the link**

Call with `channel_id`. Each call issues a new link.

**2. Give the user the link**

They open it in a browser where they are signed in to heyBTW as the person whose credential made the call. Anyone else who opens it is refused, and it opens once. It works for 30 minutes.

**3. The user imports in heyBTW**

The link opens the collab's attendee table with heyBTW's own importer open. They drop the CSV or TSV file, confirm the column mapping (registration questions map there) and import. The importer's rules apply unchanged: column mapping, status rules, duplicates, one import at a time per collab. Opened from this link, Enrich on import starts unchecked.

**4. Read the roster back**

When the user says the import is done, read it with get\_event\_details (`attendance.total`) or list\_events (`roster_count`). Do not also send the rows with record\_signups.

A link that expired or was used: call create\_import\_link again. One nobody opens expires on its own. There is no `client_request_id`: a retry simply issues another link.

## Response

The shape below is from the contract and the code (`tools/create_import_link.py`, `import-link-contract.json`). It was not called live, because each call issues a real link.

| Field | Meaning |
| - | - |
| `channel_id` | The collab. |
| `url` | The link to give the user. |
| `expires_at` | When it stops working. |
| `expires_in_minutes` | 30. |
| `single_use` | true. |

## Rules the agent must follow

* Never send the file or its rows to this tool, and never also send them with record\_signups after the user imports.
* Tell the user the link opens once, for them only, for 30 minutes.
* Read the roster back from get\_event\_details or list\_events. Never count the file yourself.
* Only the workspace's own collabs. A partner's collab, the demo collab or an unknown id returns `entity_not_found`.

## Errors and gaps

| Code | What to do |
| - | - |
| `invalid_parameter` | Fix `channel_id`. A global credential is refused: use a workspace credential. |
| `entity_not_found` | Not one of the workspace's own collabs. |
| `insufficient_scope` | The OAuth token lacks `mcp:tools:write`. No link was made. |
| `internal_error` | Retry. A retry issues another link; an unopened one expires unused. |
| 429 | Honor `Retry-After`. 30 requests per 5 s, 60 per minute, 1000 per day per workspace. |

## Related

* [record\_signups](https://heybtw.com/docs/tools/record-signups.md), for rows you already hold
* [get\_event\_details](https://heybtw.com/docs/tools/get-event-details.md), to read the roster back
* [list\_events](https://heybtw.com/docs/tools/list-events.md)
* Playbook: [Record who registered and who came](https://heybtw.com/docs/playbooks/record-who-came.md)


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