Contact import tracking and reliable row results

3 October 2026

Contact imports provide a queryable reference, per-row partial results and an error report. Updates preserve omitted fields; omitted bank_accounts preserves accounts and [] clears them. New imports consume the plan’s monthly row allowance; imports accepted under the previous exemption retain it.

New admissions share plan-limits.bulk_import_rows_per_month. Applied create/update/add_role rows consume allowance. Contact imports admitted under the previous exemption retain it. Concurrent reservations prevent exceeding the limit. Rejection occurs before writing or queueing: HTTP 429, import_row_quota_exceeded, type rate_limit_error. Row allowance is separate from stored bytes and request rate limits.

contacts:read is required for status and reports; import and preview require contacts:write. Foreign, unknown and other-module identifiers return the same 404 import_not_found. Missing scope returns 403 insufficient_scope. No company_id, internal identifiers or anonymous report links are exposed.

The synchronous response uses persisted progress: status, failure_reason and all four counters match GET. total retains the number of source records; rows and action categories include confirmed rows only, with result applied/skipped/failed. Concurrent closure can return HTTP 200 with status: failed and unprocessed_count > 0; pending rows are not reported as applied. Preview/dry-run have status: null and omit result; queued uses status: queued. The 200/202 codes described apply to HTTP; MCP returns the same JSON payload.

Reports respect the 90-day retention period. If the CSV is missing or storage cannot read it, the report is rebuilt from the ledger without writing another file. State stops advertising the report when retention expires.

• Preview a contact import
• Import contacts
• Retrieve a contact import
• Download contact import errors