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

# Customer imports

> Preview and import company members with home-branch assignments.

The `imports` module is for authorized company staff. Enable it explicitly when
connecting your assistant: open **Customize** under company data, select customer
imports, then select the individual write actions you need. Imports and write
actions start unselected. A connection without explicit OAuth scopes offers
this choice; an explicitly narrow scope must include `imports` first.
Existing connections do not automatically receive these write permissions.
Client AI connections cannot use this module.

Every call requires active staff access to the connected company, permission for
the requested action, and access to all company members and locations. Staff
with a restricted member or location scope cannot use bulk imports. The MCP
grant supplements your company permissions; it cannot expand them.

## Workflow

1. Call `get_customer_import_fields` to read supported fields and eligible branch
   IDs. Page through `references.locationPagination.nextOffset` for more branches.
2. Upload a CSV or XLSX file with `upload_customer_import_file`.
3. Map exact column headers with `analyze_customer_import` and inspect the
   returned rows, warnings and counts. Page through the complete analysis.
4. Show the intended member changes and normal invitation effects to the user.
   Obtain approval for the exact ready rows before calling `start_customer_import`.
5. Poll `get_customer_import_detail` for the actual result. A queued job is not a
   completed import. Use `get_customer_import_history` to find previous jobs.

Imports can create or link members and update existing profile or home-branch
details according to the normal customer-import duplicate rules. Bank and
financial columns and coach-column mappings are unavailable through this module.
The authenticated coach is the default assigned coach; analysis can select
another active company coach with `defaultCoachId`.

### Home branches

Map the `homeLocation` field to an exact eligible branch name or ID. A row's
branch takes precedence over `options.defaultHomeLocationId`. A blank or
unmapped value uses that default when supplied; without one it preserves an
existing member's assignment. An invalid explicit branch produces an analysis
error and never falls back to the default.

Review the canonical `preview.homeLocationId` and `preview.homeLocation` before
starting. Branch eligibility is checked again when each row is processed. A
branch that becomes unavailable causes a row failure instead of reassignment
to a different branch. This is the member's home branch, separate from their
postal address, signup location and bookings.

## Tools

All writes require an explicit per-tool grant and an `idempotencyKey`. Reuse a
key only to retry the same operation with the same arguments. Current staff
permissions are checked again for retries, including cached responses.

| Tool | Inputs | Result and permission |
| :- | :- | :- |
| `get_customer_import_fields` | Optional `locale` (`en` or `nl`), `offset`, `limit` | Supported profile/home-branch `fields`, default coach, upload limits, paginated branch references and effects. Requires `imports.view`. |
| `upload_customer_import_file` | `fileName`, canonical `contentBase64`; optional `options`, `locale` | `uploadId`, row count, detected headers and mapping proposals. Creates an upload only. Requires `imports.create`. |
| `analyze_customer_import` | `uploadId`, `mapping`; optional `defaultCoachId`, `options`, `locale`, `offset`, `limit` | `analysisId`, canonical row previews, summary, warnings and pagination. Creates a preview only. Requires `imports.create`. |
| `get_customer_import_analysis` | `analysisId`; optional `offset`, `limit` | Analysis, row previews and summary. Requires `imports.view`. |
| `start_customer_import` | `analysisId`, `selectedRowIds`, `confirm: true` | Durable `importId`, status and counts. Accepts 1–1000 selected ready rows. Requires `imports.create`. |
| `get_customer_import_detail` | `importId`; optional `offset`, `limit` | Job status/counts and paginated row outcomes under `analysis`. Requires `imports.view`. |
| `get_customer_import_history` | Optional `cursor`, `limit` | Newest company MCP customer jobs, `items` and `nextCursor`. Requires `imports.view`. |
| `cancel_customer_import` | `importId`, `confirm: true` | Updated job. Only the originating coach's queued job can be canceled. Running or finished jobs cannot be canceled here. Requires `imports.cancel`. |

Uploads and analyses used for a new import must belong to the requesting coach
in the connected company. Authorized staff can view company MCP analyses and
jobs created by other company coaches. Admin imports are outside this module.

Upload filenames must be plain filenames ending in `.csv` or `.xlsx`; paths and
URLs are rejected. The decoded file limit is 10 MiB. `options` accepts only
`delimiter` (comma, semicolon, tab or pipe) and `defaultHomeLocationId` (an eligible
branch ID). Supplying financial options or unsupported mappings is rejected.

Mapping is an array of exact source headers and supported field IDs. Use an
empty `fieldId` to ignore a column. For example:

```json theme={null}
{
  "uploadId": "upl_0123456789abcdef01234567",
  "mapping": [
    { "header": "First name", "fieldId": "firstName" },
    { "header": "Last name", "fieldId": "lastName" },
    { "header": "Email", "fieldId": "email" },
    { "header": "Branch", "fieldId": "homeLocation" }
  ],
  "options": { "defaultHomeLocationId": "0123456789abcdef01234567" },
  "idempotencyKey": "analyze-members-2026-10-29"
}
```

Row and branch lists use `offset` and `limit` (default 50, maximum 100). Continue
with `nextOffset` until it is null. History uses `cursor` with `nextCursor`
(default limit 20, maximum 100). Row statuses, issues and actual outcomes may
differ after processing; inspect all result pages and counts.

Retrying a start with the same analysis and exact row selection returns its
existing import; it never creates a second job. A retried start can resume a
queued import without repeating its member changes. If an interrupted
request keeps returning `COMPANY_MCP_IDEMPOTENCY_IN_PROGRESS`, first check job
history/detail. After reviewing the same approved selection, use a new request
key to recover that existing import. A changed selection conflicts with an
already committed analysis.

## Individual changes

For one member, use the [clients tools](https://docs.fitsociety.io/mcp/tools/clients.md#home-branches) to list
eligible home branches, view the current assignment, or update/clear it with
confirmation. These tools respect the staff member's individual member and
location scope.


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