This article guides you through importing or updating contact data in bulk via a CSV file. Now that MAAC has been upgraded to an omnichannel platform, you can also import Email (EDM) and WhatsApp contact lists.
# Import Fields and Format
To ensure your data imports correctly, prepare your CSV file according to the table below. Different channels may have specific required fields.
LINE channel import
| Field name | Description | Required | Updatable | Notes |
| line_uid | LINE user UID | No | ❌ | Primary identifier field for LINE contacts |
| phone | Contact phone | No | △ |
|
| customer_id | Brand's custom contact ID | No | ✅ | Recommended to be unique; used to sync external data |
| name | Display name | No | ✅ | Overwrites the original value when a value is present |
| Email address | No | △ |
|
|
| note | Note field | No | ✅ | Overwrites when a value is present |
| tags | Tags | No | ✅ | Separate with commas; merged on add |
Email (EDM) channel import
Used for importing Email marketing lists. Note that EDM imports have strict status (Status) validation to protect sending reputation.
| Field name | Description | Required | Notes |
| Email address | Yes | The contact's email address. This field is required and serves as the primary identifier for an EDM channel contact. | |
| messaging_ status |
Subscription status | Yes | Enter the contact's subscription status for the brand's domain. The value must be one of: "subscribed", "unsubscribed", "hard_bounce", or "spam_report". |
| display_name | Display name | No | Must not exceed 255 characters. |
| gender | Gender | No | Must be one of the following values: "female", "male", or "unknown". |
| customer_id | Brand's custom contact ID | No | Recommended to be unique; used to sync external data |
| mobile | Phone | No | The phone number must follow regional conventions or the E.164 format. For example, acceptable formats for Taiwan are "0912345678" or "+886912345678". |
| birthday | Birthday | No | Only the YYYY-MM-DD format is accepted. |
| tag | Tags | No | Separate with commas; merged on add |
| consent_source | Consent source | No | The source where the contact gave consent (for example: "Website Footer", "Checkout"). This field is for future audit purposes. |
| consent_at | Consent time | No | The exact time the contact gave consent. The format must be YYYY-MM-DD hh:mm:ss. This field is for future audit purposes. |
📌 After importing Email contacts, to actually use the "Send Email" node in an automated journey, the contact status must be Subscribed, your brand's Email channel must be Connected, and there must be at least one available Sender Profile.
👉 If you still cannot send Email in a journey after importing, first see: Onboarding Guide｜How to Enable Email Channels and Import Contacts
WhatsApp channel import
Used for importing WhatsApp contact phone lists. This channel must include the status field, or the import will fail.
| Field name | Description | Required | Notes |
| WhatsApp_mobile | WhatsApp phone number | Yes | This field is required. The column header must not be deleted or reordered. The phone number must follow regional conventions or the E.164 format. For example, acceptable formats for Taiwan are "0912345678" or "+886912345678". |
| messaging_ status |
Subscription status | Yes | This field is required. Be sure to enter one of the following values: "opted_in", "opted_out", or "not_subscribed". |
| display_name | Display name | No | Must not exceed 255 characters. |
| gender | Gender | No | Be sure to enter one of the following values: "female", "male", or "unknown". |
| customer_id | Brand's custom contact ID | No | Recommended to be unique; used to sync external data |
| No | The phone number must follow regional conventions or the E.164 format. For example, acceptable formats for Taiwan are "0912345678" or "+886912345678". | ||
| birthday | Birthday | No | Only the YYYY-MM-DD format is accepted. |
| tag | Tags | No | Separate with commas; merged on add |
# How to Choose the "Matching Field" (Key)
Before importing, you must select 1 field as the matching basis (Key), which the system uses to decide whether to "update" or "add" a contact:
| Key | Description | Recommended use case |
| line_uid | LINE user UID | Contacts created from a webhook |
| phone | Contact phone number | Importing WhatsApp lists, phone lists, offline data |
| Contact Email | Use when importing an Email subscriber list. | |
| customer_id | Brand's custom unique value | CRM systems, API integration users |
⚠️ Note: If the system has multiple contacts sharing the same phone, it updates the one with the "later creation time." To avoid updating the wrong contact, we recommend using line_uid or customer_id.
📌 If you plan to integrate Email contacts and LINE contacts into the same omnichannel automated journey, we recommend going to Customer Data Hub (CDH) at the same time and setting Email as a Unify Key, to reduce duplicate cross-channel communication.
# Include Custom Fields When Exporting Contacts
When you export a list from the "contact list," the interface shows an additional "Custom fields" section to select. You can decide freely which custom field data to include in this download (for example, selecting to export "Membership tier"), making your offline analysis afterward easier.
Export steps:
- Go to "Contact Management" → "Export"
- In the export settings, select the "Custom fields" you need
- Click "Export," and the system generates a CSV file that includes the custom field data
In the exported CSV file, custom field headers automatically carry a
cl_custom_ prefix. If you need to modify this file and re-import it, keep this prefix format so the system can identify the fields correctly.
# System Behavior After Import
| Behavior | Result |
| Key matches | Updates that contact's data (only overwrites the fields that have a value) |
| Key does not match | Creates a new contact (no new contact is created if the Key is customer_id) |
| Incorrect field name | That field is skipped |
| tags has multiple values | Merged; the original tags are not overwritten |
| Attempting to update a channel primary key (line_uid / email / WhatsApp_mobile / SMS phone) | Ignored by the system; not updated |
# Update Notes
- Empty fields do not overwrite the original data
-
Custom field CSV headers must start with
cl_custom_followed by the field identifier, and must match the settings in Admin Center exactly - If multiple matching fields are provided at once, the system uses the Key as the primary one
- LINE UID / WA mobile / email / phone (SMS) are non-updatable fields
- An Email contact's email field is not overwritten
# Channel Import Restrictions
A. Email (EDM) contact import
Important import restrictions
To comply with international anti-spam regulations and protect domain reputation, MAAC enforces a strict "status is irreversible" rule:
🚫 You cannot use a CSV import to change an "Unsubscribed" or "system-suppressed" contact back to "Subscribed."
- If you try to change Unsubscribed to Subscribed in the CSV, the system will ignore that status update and only update the other fields (such as name and phone). This prevents sending to addresses that have explicitly opted out or are invalid, keeping your brand off blocklists.
Automatic Suspension Policy
To maintain sending quality for all users, the system has automatic monitoring in place. If your sending domain shows the following conditions, the system will automatically suspend your sending capability:
-
Trigger conditions (within the past 24 hours):
- Hard Bounce: too many sends to nonexistent mailboxes—more than 20 times and a bounce rate > 5%.
- Spam Report: too many users marking your email as spam—more than 10 times and a complaint rate > 0.5%.
-
How to recover?
- First, use a third-party tool to clean your Email list and exclude invalid addresses.
- Import the cleaned results into MAAC to update contact statuses.
- Notify your CSM to help request reinstatement; after manual review, it is restored manually from the backend.
⚠️ Because the Email (EDM) channel uses a shared IP, one abnormal sender harms all customers. Customers must use only consented, subscribed lists. Purchased or scraped lists must not be used.
B. WhatsApp contact import
Important import restrictions: required status and format
status field in the CSV is absolutely required.Allowed values:
opted_in (consented), not_subscribed (not subscribed), opted_out (opted out).System behavior: if a row's
status field is empty, the system directly "skips that row" (Skip) and does not import or update it at all.
+886912345678). If the format does not match, the system cannot create a valid WhatsApp contact, causing sends to fail.
Meta account quality and suspension (Quality & Suspension)
not_subscribed) or who have opted out (opted_out) very easily leads to blocks or reports. This causes a drop in account rating, a downgrade of daily quota, and in severe cases suspension of the WABA account.
# Steps to Import Contacts
Step 1: Download the import template
Go to Contact Management, click Import / Update Contact Data, and download the CSV import template provided by the system.
We recommend exporting your existing contact data first, to confirm the field names and Key are consistent and avoid creating duplicate contacts.
Step 2: Upload the file
Step 3: View the results
# Identity Unification and Conflict Handling After Import 🆕
After the import completes, the system runs identity unification in the background, deciding which contacts belong to the same person and grouping them into a single unified contact based on the Unify Keys you configured. The whole process has two stages:
- Import complete: the CSV list has finished being created / updated, and you receive a notification (the bell icon).
- Unification complete: the background identity unification finishes grouping.
Because identity unification runs in the background, "import complete" does not mean "unification complete." Wait a moment, and after unification completes, return to the contact list or the Unified Contact Profile to confirm the grouping is correct.
When an Import Causes an Identity Conflict
If, during unification, multiple contacts that may be the same person are found to carry different Customer IDs, the system does not merge them automatically—to avoid an incorrect merge—and marks them as an identity conflict. In that case:
- The notification center shows "Identity conflict detected: X not merged automatically (Customer ID)," and offers a download of the conflict list.
- You can also download the list of contacts still in a conflict state from the contact list's Export > Export conflict contacts.
Correct and re-trigger grouping:
- Download the conflict list and confirm whether the related contacts truly belong to the same person.
- Correct the incorrect Customer ID, or fill in the correct identifiers.
- Re-import the corrected list, and the system re-runs identity unification.
If a channel contact was manually "split" and had identity unification disabled, re-importing its correct identifiers also re-triggers grouping; once unification completes, the "split" marker disappears. For details, see Tutorial | Unified Contact Profile and Splitting Contacts.
👉 To download the conflict list and see the CSV columns: How to Export Contacts and the Data Mapping Table. For how conflict detection works: Feature Description｜Contact Field Definitions and Matching Logic.
# FAQ
Q: If the imported phone has multiple duplicates in the system, which one gets updated?
A: The system updates the contact with the "later creation time." To avoid updating the wrong contact, we recommend using line_uid or customer_id as the matching basis.
Q: When importing tags, are existing tags overwritten?
A: No. Imported tags are automatically merged with existing tags; the system does not delete existing tags.
Q: Why didn't some fields update successfully?
A: Possible reasons:
The field was empty in the import file; the field name does not match the admin settings; the field is a "channel primary key" and is non-updatable (line_uid, WhatsApp_mobile, email (EDM primary key), SMS phone); when using customer_id as the Key, if the system does not have that customer_id, no new contact is created.
Q: Can I add and update contacts at the same time when importing data?
A: Yes. The system automatically decides whether each row is an update or an addition based on the Key you selected. However, if you use customer_id as the Key, the system only updates existing contacts and does not add new ones.
Q: Why were contacts merged after import?
A: MAAC merges data automatically based on Profile Unification rules. As long as any of the following fields matches an existing contact, they are merged into the same Profile: email, phone, customer_id, line_uid, WhatsApp_mobile, fb_id, ig_id.
Q: Why weren't some contacts merged automatically, and an "identity conflict" appeared?
A: When multiple contacts that may belong to the same person carry different Customer IDs, the system does not merge them automatically—to avoid merging different people incorrectly—and marks them as an identity conflict. Download the conflict list, confirm whether they are the same person, correct the Customer ID or fill in the correct identifiers, then re-import; the system will re-run the grouping.
Q: After the import completed, why hasn't the grouping result updated?
A: Identity unification is a background process; the "import complete" notification does not mean "unification complete." Wait a moment, and after the background unification finishes, return to the contact list or the Unified Contact Profile to confirm the grouping result.
Q: Why were some rows skipped during a WhatsApp import?
A: WA imports require two mandatory fields: WhatsApp_mobile and status. If status is empty (opted_in / opted_out / not_subscribed not filled in), the system skips that row and does not import it.
Q: I've already imported Email contacts, so why still can't I send Email in an automated journey?
A: There are three common reasons. First, the contact's messaging_status is not Subscribed. Second, your Email channel is not yet Connected. Third, there is no available Sender Profile in the system. Importing contacts only completes list creation; you must also satisfy the channel and sending conditions for the "Send Email" node in a journey to work properly.
Q: When importing custom fields, the system says the field cannot be found—what should I do?
A: Check your CSV file header. The system requires custom fields to carry the cl_custom_ prefix, with the correct format being cl_custom_{field_identifier}. Go to Admin Center to confirm the spelling of the field identifier, and make sure the field status is "active" rather than "archived."
Q: What format requirements do imported custom field values have?
A: Different field types have different format requirements:
- Text: free-form text string
- Number: numbers only (decimals allowed)
- Date: only the YYYY-MM-DD format is accepted
- DateTime: the YYYY-MM-DD HH:mm:ss format is accepted; the system stores it as UTC+0