Import contacts from CSV
Upload a contact file and check which rows were imported.
Reviewed
The CSV importer accepts files up to 25 MiB with a header row and up to 200,000 data rows. Split larger files before uploading. Oversized files are rejected before reading their contents. It creates new phone records, updates matching contacts, and reports invalid or duplicate rows after processing.
Prepare the file
Include one contact per row. A phone column is required. The importer can map these fields:
| Waaru field | Requirement |
|---|---|
| Phone | Required. Use a complete WhatsApp number. |
| First name | Optional |
| Last name | Optional |
| Optional | |
| Country code | Optional ISO region, such as IN; not a phone prefix |
| Locale | Optional, such as en_IN |
| Tags | Optional. Separate names with semicolons |
| Custom columns | Optional. Place these columns anywhere |
Use clear column names such as phone, first name, last name, email, and country code. Waaru attempts to recognize common alternatives, but you should review every mapping.
Select Download sample CSV to fetch the workspace's current active custom fields and download them with the standard fields and Tags. A column named taxSlab becomes the custom key tax-slab. New keys use lowercase letters, numbers and single hyphens. Review mappings to existing or new fields before importing; creating a new workspace field requires an administrator. New fields start as Text; select Number, Boolean or Date when needed. Duplicate or colliding keys must be corrected before importing.
Standard field names and their aliases, such as country or mobile, belong to standard mappings. To import a custom field with one of these names, put it in a customAttributes JSON object, such as {"country":"India"}. The sample uses JSON for these fields. Skipping an ambiguous populated column that matches an active custom field blocks preparation; move its values to JSON or remove the column before importing.
The defaults are 30 active workspace field definitions and 30 values per contact; only Waaru administrators can change these limits. The importer validates each mapped field's type. Date fields in CSV columns and custom JSON must use a real calendar date in DD/MM/YYYY format, such as 18/09/2026. Timestamps and dates such as 30/02/2026 are rejected; APIs continue to use ISO timestamps. The optional JSON column remains available for reviewed custom values. Blank cells omit a value. Supplied values update their matching keys while unrelated values already on a contact remain unchanged. Review the preview before updating existing contacts.
Tags append to existing assignments. Matching names reuse the workspace's contact tag catalogue; missing names are created. Manage the catalogue later in Settings > Contact tags. Each row supports up to 50 tag names, with at most 48 characters per name.
Requests are split by both row count and UTF-8 byte size. The request limit remains 1 MiB, and a changed custom field value may use up to 16 KiB of JSON UTF-8. A value or contact too large for its bound is rejected before import starts.
Run the import
- Open Contacts and select Import CSV.
- Drop the file into the upload area or select it from your device.
- Map the CSV columns to Waaru fields. Confirm that Phone is mapped.
- Choose no segment, an existing static segment, or a new static segment for the imported contacts. Dynamic segments evaluate their rule and do not accept manual membership.
- Review the preview and row count.
- Confirm that you have permission to contact the people in the file.
- Start the import and keep the dialog open until the result appears.
Imports are processed in durable batches. If an import pauses after a temporary failure, start it again with the same file to continue from completed work.
Read the result
The completion screen separates created contacts, updated contacts, duplicates within the upload, invalid rows, new segment additions, and contacts who were already members. Phone and field errors found during preparation block writes and identify the CSV record number, including the header and empty records. Errors encountered after importing starts retain completed batches; correct the file or retry the paused import as appropriate.
Within one upload, the first occurrence of a normalized phone number wins across all batches; later occurrences do not change the contact or its tags. Starting a separate import updates an existing contact rather than creating another phone record. Confirm the result before launching a campaign, especially when the import also changed segment membership.
Next: Review consent and segments.
Contact exports use phone_e164, custom_attributes_json and label_names_json. Before reimporting, remove keys whose field definitions are archived or restore those fields in Settings. Exports retain those values, and the importer rejects archived keys. The importer reads exported tag arrays and ignores export metadata. Exported custom Date values use DD/MM/YYYY for the UTC calendar day; importing them keeps that day at midnight UTC, so time-of-day precision is not retained. Operational metadata timestamps stay in ISO format. Import and export use the UTC calendar day consistently, independent of browser or workspace timezone. The contact editor displays local date-time, which can show the preceding day west of UTC.