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