Import customers and their complete project history

A company administrator can use Settings → Import Data for leads/customers, jobs/sales, appointments, payments, dated notes, quotes, financing records, additive financial entries, and photos/documents. Keep an untouched copy of the original export and uploaded files. The importer adds history; it does not send emails or texts, activate follow-ups, or queue reminders for imported appointments.

Choose a stable lower-case source identifier such as marketsharp. Preserve each original record ID as external_id. Do not use spreadsheet row numbers or regenerate IDs between batches. Parent fields such as lead_external_id and job_external_id refer to IDs previously imported under that same source.

Import contacts first, then jobs, then appointments, payments, notes and quotes. A quote can optionally reference an imported appointment, so import that appointment first. Files also need the original contact reference. Each batch contains one record type, up to 500 rows and 2 MB of CSV/JSON data.

Download the current template for the selected type. Its canonical field names and required fields are authoritative. Map your source columns, preserve postal codes and original IDs as text, use YYYY-MM-DD dates, 24-hour appointment times in the company timezone, and ISO timestamps with a timezone for dated history. Monetary amounts require decimal values with at most two fractional digits. Only an explicitly authorized contract adjustment may be negative. Payments are historical ledger entries, not a request to charge a card.

Import jobs and payments first, then financing_records, then financial_entries. Use job_external_id and optional payment_external_id or financing_external_id from the same source. An existing_service_ticket_id must be the exact UUID of a ticket in the same company and job; linked warranty amounts must match that ticket’s current parts and labor snapshot. Never infer historical fees, funding or warranty costs.

Card and financing fees, other costs and explicitly recorded warranty costs reduce margin. Refunds reduce net receipts only; a separate signed contract_adjustment records an agreed price change. Financing amounts and customer interest rates do not create receipts or dealer fees. Original job sale amounts and gross payments remain unchanged. Replays are skipped, changed original IDs conflict, and duplicate linked payment fees or warranty snapshots are blocked. Record only costs that are not already included elsewhere.

Review each batch before any customer history is saved.

An unchanged source/type/external_id is skipped on a repeat import. Reusing that ID with changed values causes a conflict instead of overwriting the customer file. Full normalized phone/email matching can link an existing contact only when the identifying details agree. Conflicting or multiple matches stop the import. Names and last-four phone digits are not sufficient identifiers.

Concurrent retries are serialized and repeat commits reuse the completed result. If a preview becomes stale because a customer, parent, or duplicate candidate changes, generate a new plan. A failed transaction does not partially create the batch. There is no automatic merge of households, silent repricing, or broad delete/undo operation. Preserve originals and resolve issues before committing.

Importing a contact does not opt them into texting. Preserve known opt-outs and reconcile original form/provider evidence separately. If the old system never tracked individual consent, use the legacy-unknown annotation through an authorized MCP workflow instead of marking every phone opted in. See the text consent guide for exact tools and safeguards.

Keep automation drafts off while the old CRM is still sending. Imported appointments, notes and payments are history and must not replay old events as new leads. After reconciling counts and totals, preview intended recipients and exclusions and obtain administrator approval before live messaging.

CSV cannot contain image or PDF bytes. In the Photos and documents mode, stage a PDF, JPEG, PNG, or WebP file up to 10 MB with its stable original file ID and original customer ID. Download the staged-file manifest and preview it as a files import. Staging alone does not attach the file to a customer.

An authorized migration assistant can upload raw file bytes to the documented staging endpoint and use the returned existing_file_id in its file rows. Existing company-owned uploaded file IDs can also be referenced. Arbitrary remote URLs and local filesystem paths are rejected. Files stay private and are downloadable only after a committed attachment and normal customer-access checks. Referenced files are retained; previews expiring does not delete saved customer documents.

In Settings → AI setup, create a new trusted connection and explicitly enable customer history migration. Existing setup-only connections do not gain customer access. Keep the connection key in the assistant’s secure settings; do not paste it into customer records or CSV files.

The assistant can discover templates, stage files, and prepare a preview using get_import_templates and preview_customer_import. In Settings → Import Data → AI import reviews, review the actual source values and totals, then approve that exact plan. The assistant can check get_import_review and call apply_approved_import before expiry. By default the assistant cannot approve itself. Optionally, the administrator who created that migration connection can enable AI review & approval in Settings → AI setup. The assistant must inspect every source row, mapping, duplicate decision, relationship and total, then call approve_import_review with the exact plan digest and a concrete review note before applying. This authorizes that assistant to save valid customer-history batches without further manual approval. Unresolved issues still block the entire batch. The AI cannot change the approved plan, import another company’s data, approve setup settings, or bypass current administrator permissions. Disable delegation to invalidate unconsumed AI approvals; turning it back on does not revive old approvals.

A plan approval saves no customer rows by itself. Revoke the connection after the migration if ongoing access is unnecessary. This workflow can support a separate assistant handling the migration while another person reviews batches inside the CRM.