Import jobs (dark)

A reusable CRM migration feature for any GoodQA organization. The operator must enable imports.enabled; this lane ships it off by default. Use the CRM Import CSV wizard, the REST API, or ask a bot for a dry run.

1. An org admin with crm:import submits POST /v1/orgs/{orgId}/imports.
2. Review the report: creates, updates, duplicates, row errors, unknown columns, DND counts, address preservation and up to 20 samples.
3. A signed-in person sends {reportSha256} to POST /v1/orgs/{orgId}/imports/{id}/commit. Each call applies up to 100 rows.
4. Repeat with the same hash until complete; GET the job for row outcomes. Target conflicts need a new dry run. Errors never silently overwrite data.

Example invented file:

{"profile":"highlevel_csv","object":"contacts","source":"my_location","csv":"Contact Id,First Name,Email,DND\nhl-1,Demo,demo@example.test,true"}

Profiles generic_csv and highlevel_csv support contacts, companies and opportunities. Maximum CSV: 1 MiB UTF-8, 1,000 data rows, 100 columns. Oversized files are refused; split them before uploading. HighLevel's own upload limit differs; it does not increase GoodQA's cap.

Optional mapping uses zero-based column indexes. Targets: externalKey, firstName, lastName, email, phone, name, domain, notes, tags, title, stageId, pipeline, stage, value, valueCents, currency, primaryContactId, companyId, contactExternalKey, companyExternalKey, doNotContact, additionalEmails, additionalPhones, field:<key>, or null. Custom fields must be existing text fields. Tags must already exist; tags apply to contacts and companies. Related record UUIDs must belong to your org. Targets must belong to the selected CRM object: for example, name and domain belong to companies; contact names use firstName/lastName (HighLevel Name is suggested as firstName). Company imports currently accept name/domain/notes/tags/text fields; contact addresses and DND must be imported as contacts. New opportunities require a source id, title and a GoodQA stage UUID or pipeline/stage names that match exactly one active stage. HighLevel Contact Id and Company Id resolve earlier imports in the same org/source namespace. Existing opportunities also accept partial title, value or currency updates. Map valueCents for integer cents or value for nonnegative decimal amounts (up to two decimal places); excess precision/overflow is refused. Importing a changed stage is refused; use the ordinary stage route.

Source ids use externalKey, optionally prefixed by source (use a stable source per HighLevel location). Without a source id, contacts match email then phone; companies match domain. Multiple addresses in a cell may use semicolons, commas or pipes. First is primary; extras become custom text fields, visible in the report. No address is silently discarded. Phone numbers need country codes.

DND/unsubscribed/opt-out columns are inspected even if your mapping ignores or renames them. Ambiguous values are row errors. DND suppresses every known address before record writes. Imports never record consent or contact basis and never clear existing do-not-contact. Credential-like content is refused before storage; reports contain customer data and require org-admin access.

HighLevel contact exports may truncate the latest note to 255 characters and omit message history. The report warns about this; CSV cannot restore those missing notes, workflow definitions, funnel designs or conversation history. A read-only HighLevel API profile is future work.

MCP tools: import_dry_run, import_status, import_commit. The commit tool returns the real route's refusal with machine credentials; a person must use a browser session to commit. Design.

API reference, MCP tools, operator runbook.

• Runbook: Import operations

In the web CRM Contacts header, Import CSV opens a mapping/review wizard while the flag is on. Upload a file, review the server report, acknowledge it, then apply the next 100 rows. Save the job ID to resume with Load report after a refresh. CRM create/edit permissions and a person session are required to apply. The ordinary contact-import dialog remains available while the flag is off. No provider credentials, payment connections or invoices are imported.

New contacts, companies and opportunities carry the existing CRM acquisition source import, so source reports distinguish migration from manual entry. Updates preserve the record's original source; this metadata grants no consent or outreach basis.