Contacts: import from a file, fix refused rows, search, download

This chapter shows you how to move your contacts into SMS CRM from a file, what the results of an import mean (including rows that get refused and how to fix them), how to search your list, and how to download it again.

Before you start — who this is for

Any business member using the contacts screen. Two things to know up front:

Step 1 — choose your file and confirm it

Open the import, pick your file, and confirm. Until you confirm, nothing happens. In the verification run, after a refused attempt the database showed zero new contacts, zero import records and zero message sends for the customer — a refusal really does leave nothing behind.

Step 2 — enter your MFA code with the import

  1. Try submitting the import without your current MFA code — the screen visibly refuses, and your draft stays put so you do not retype anything.
  2. Enter the current code from your authenticator and submit again.
  3. The import goes through.

What you see afterwards: a summary of the import — how many contacts were added, and any rows that were refused with the reason for each. A refused row is kept on the record with its reason — it is never silently thrown away. Fix the row in your file and import again.

In the retained verification run, the retried import stored two contacts plus one refused row; the saved import record, the refusal reason and the contact records were all read back directly from the database to confirm it. A separate approved round-trip check showed the same contract: one imported, one duplicate kept, one refused — and the saved contact and import record were still there after a page reload. Importing grants no consent or opt-in of any kind (see Contact timeline and privacy).

Step 3 — what each row of your import becomes

When your file contains a mix of good and problem phone numbers, every row lands in exactly one of three buckets — imported, duplicate, or refused with a reason. Nothing is silently dropped, and no half-row is ever written. The import finishes with status "completed" and one audit entry carrying the same counts.

The accepted phone shape is a +-prefixed international number of 8 to 15 digits (for example +919876543210). A verified 10-row mixed file behaved like this:

Your file row What was in it Message you get
Row 8 +9112345 (7 digits — too short) phone "+9112345" is not a plausible E.164 number
Row 9 +91987654321098765 (17 digits — too long) phone "+91987654321098765" is not a plausible E.164 number
Row 10 not-a-phone (no digits at all) phone "not-a-phone" is not a plausible E.164 number
Row 11 empty phone cell phone is required

The row numbers are the physical row numbers in your file (the header is row 1, so your data rows start at row 2) — open the file, fix exactly those rows, and import again.

Two guarantees worth knowing:

If you import the same file again

That is safe. In the verified run, re-importing the exact same file reported 0 imported, 6 duplicates, 4 refused — the five stored contacts plus the in-file duplicate now all count as duplicates, and the same four invalid rows refuse again with the same reasons and row numbers. A before/after database comparison confirmed the stored names and captured times were untouched: re-importing never overwrites or duplicates what you already have.

If the whole file is unusable

If the file's structure itself is wrong (in the verified case: a header line that is not a recognizable contacts header), the entire file is refused — you see the refusal, and nothing is saved: no import record, no contacts, no refusal rows. Your earlier imports and contacts are untouched. Fix the file (or its header) and import again.

About international numbers

A non-Indian number is not an error — it lives happily in your CRM (search, export and timeline all work for it). One thing to know: the SMS delivery-evidence feature (see SMS delivery evidence) currently works with Indian mobile numbers only. The system itself refuses to match or save delivery records against any non-Indian number, so a +44 or +1 contact can never get a delivery record attached by mistake. That refusal was verified for every non-Indian identity, including the 8- and 15-digit boundary numbers.

Step 4 — search your list

Type in the contact search box and the list narrows to matching contacts you are allowed to see. Search matches names, phone numbers and Unicode text (non-English letters included), verified against real records.

Step 5 — select a contact to see their own activity

Clicking a contact shows that contact's own timeline entries only — no other contact's entries ever appear in it. In the verification, selecting "Alpha" showed Alpha's note and excluded Beta's; selecting Beta switched to Beta's note. See Contact timeline and privacy for what the timeline does and does not contain.

Step 6 — download your list

Downloading from a filtered view gives you exactly the contacts you are allowed to see — the retained download contained the complete two-contact result and no contact from any other business (the downloaded file itself is kept as proof). If a server problem happens mid-download, you see an error and the stale partial file is removed — after the problem clears, reload the page and your list comes back.

Step 7 — refreshing is safe

Refreshing the page simply restores your saved contacts, the linked board and your import records (including the original refusal reasons). In the verification run, the final database state was still exactly two contacts, one import record and zero message sends.

If something goes wrong — quick reference

What you see What it means What to do
Import refused, asking for your code The current MFA code was missing or wrong Enter the current code from your authenticator and submit again; your draft stays
Rows refused with "not a plausible E.164 number" / "phone is required" Those phone numbers are missing, empty, or outside the 8–15 digit +-prefix shape Fix exactly those rows in your file (the row numbers are given) and import again
Whole file refused The file's structure/header was not recognized Fix the file or its header; nothing was saved, your earlier data is untouched
Error during download A server-side fault interrupted it The stale download is removed automatically; reload after the fault clears
Duplicate counts on re-import Those contacts already exist Nothing to do — existing contacts are never overwritten

Your data stays yours (privacy guarantees)

With the same signed-in test identity, the verification deliberately tried to reach another business's data — and the server itself refused every time:

Evidence and receipts

Fact in this chapter Receipt
MFA refusal, retry, two contacts + one rejected row, SQL witnesses, refresh tools/chief-sms-crm-review-20261012/actual-http-pg/HANDOFF.md ("Executed outcomes"), attempt02/ outputs, final-sql-witness.json
Screenshots of the real utilities (fixture data) attempt02/actual-customer-utilities-1440.png, attempt02/actual-customer-utilities-390.png
Foreign-org 403 / foreign contact 404 / RLS zero tenant-refusal.json in the same root
34 HTTP / 438 SQL receipts, 216 pinned modules (custody counts for this run only) same HANDOFF, "Final passing attempt"
Preserved failure (fixture remount, not a product defect) attempt 01 result.json and attempt history in the HANDOFF
Search name/phone/Unicode; import round trip 1+1+1, receipt after reload tools/sms-crm-approved-overview-20261013/HANDOFF.md, evidence/run06/result.json (19/19), evidence/run07/result.json (1/1)
Phone-outcome section: 5 imported / 1 duplicate / 4 refused, exact messages, physical row numbers C:/CT-ZC-3867-smscrm/services/wa-app/tests/sms-crm-import-phone-outcomes.test.ts (commit 8d779dd7, 6/6 twice) and C:/CT-ZC-3867-smscrm/docs/delivery/evidence/3867-j3-import-phones-20261025/import-phone-outcomes-receipts.json (independent rerun: 3867-j3-rerun/)
No partial rows; header counts 5+1+4; one audit row; ledger keeps every refusal same receipts JSON (stored-after-mixed-import, final-state entries)
Retry = 0/6/4, nothing overwritten same receipts JSON (mixed-phones.csv(retry) entry)
Headerless file refused whole, zero writes same receipts JSON (structural-refusal entry)
India-only delivery-evidence gate refuses every non-Indian identity same receipts JSON (phone-gate entry)
Lane status, reproducibility, boundaries C:/CT-ZCODE-FULL3747/lane-3867smscrm-ledger.json (worker lane, not Chief-accepted)