This article guides you through importing or updating contact data in bulk via a CSV file. As MAAC has been upgraded to an omnichannel platform, you can now also import Email (EDM) and WhatsApp contact lists.

To ensure data is imported 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 identifying field for LINE contacts
phone	Contact phone	No	△	The phone field of WhatsApp contacts cannot be edited The phone field of contacts on other channels can be edited
customer_id	Brand-defined contact ID	No	✅	Recommended to be unique; used to synchronize external data
name	Display name	No	✅	Overwrites the original value if a value is present
email	Email address	No	△	The email field of Email contacts cannot be edited The email field of contacts on other channels can be edited
note	Note field	No	✅	Overwrites if a value is present
tags	Tags	No	✅	Separated by half-width commas; merged and added

Email (EDM) channel import

Applies to importing Email marketing lists. Note that EDM import has a strict status (Status) validation mechanism to protect sending reputation.

Field name	Description	Required	Notes
email	Email address	Yes	The contact's email address. This field is required and serves as the primary identifying field for EDM channel contacts.
messaging_ status	Subscription status	Yes	Enter the contact's subscription status for the brand domain. The value must be one of the following: "subscribed", "unsubscribed", "hard_bounce", or "spam_report"
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-defined contact ID	No	Recommended to be unique; used to synchronize external data
mobile	Phone	No	The phone number must comply with regional standards or use the E.164 format. For example, acceptable formats in Taiwan are "0912345678" or "+886912345678".
birthday	Birthday	No	Only the YYYY-MM-DD format is accepted.
tag	Tags	No	Separated by half-width commas; merged and added
consent_source	Consent source	No	The source where the contact provided consent (for example: "Website Footer", "Checkout"). This field will be used for future auditing purposes.
consent_at	Consent time	No	The exact time the contact provided consent. The format must be YYYY-MM-DD hh:mm:ss. This field will be used for future auditing purposes.

📌 After importing Email contacts, if you want to actually use the "Send Email" node in an automated journey, in addition to the contact's status being Subscribed, the brand's Email channel must also be Connected, and there must be at least one available Sender Profile.

👉 If you still cannot send Email in a journey after importing, see first: Tutorial｜How to Enable the Email Channel and Import Contacts

WhatsApp channel import

Applies to importing WhatsApp contact phone lists. This channel must include the status field, otherwise the import is not possible.

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 comply with regional standards or use the E.164 format. For example, acceptable formats in 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-defined contact ID	No	Recommended to be unique; used to synchronize external data
email	Email	No	The phone number must comply with regional standards or use the E.164 format. For example, acceptable formats in Taiwan are "0912345678" or "+886912345678".
birthday	Birthday	No	Only the YYYY-MM-DD format is accepted.
tag	Tags	No	Separated by half-width commas; merged and added

# How to Choose the "Matching Field" (Key Value)

Before importing, you must select 1 field as the matching basis (Key value); the system uses it to determine whether to "update" or "create" a contact:

Key value	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
email	Contact Email	Used when importing Email subscriber lists.
customer_id	Brand-defined unique value	CRM systems, API integration users

⚠️ Note: If multiple contacts in the system share the same phone, the one that was "created later" will be updated. To avoid incorrect updates, 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 also going to Customer Data Hub (CDH) and setting Email as a Unify Key to reduce duplicate cross-channel communication.

# Including Custom Fields When Exporting Contacts

When you export a list from the "Contact List", a "Custom Fields" section appears in the interface for you to select. You can freely decide which custom field data to include in this download (for example, choosing to export "Membership Tier"), making subsequent offline analysis more convenient.

Export steps:

Go to "Contact Management" "Export"
In the export settings, select the "Custom Fields" you need
Click "Export", and the system will generate a CSV file containing the custom field data

📌 Additional notes
In the exported CSV file, the custom field headers will automatically carry a cl_custom_ prefix. If you need to modify this file and re-import it, please keep this prefix format so the system can recognize it correctly.

# System Behavior After Import

Behavior	Result
Key value matches	Updates that contact's data (only overwrites the fields that have been filled in)
Key value not matched	Creates a new contact (if the Key value is customer_id, no new contact is created)
Wrong field name	Skips that field
tags has multiple values	Merges them; does not overwrite the existing tags
Updating a channel primary key (line_uid / email / WhatsApp_mobile / SMS phone)	The system ignores it; it will not be updated

# Notes on Updating

Empty fields do not overwrite the original data
The CSV header of a custom field must start with cl_custom_ followed by the field identifier, and must exactly match the settings in the Admin Center
If multiple identifying fields are provided at the same time, the system takes the Key value as the primary basis
LINE UID / WA mobile / email / phone (SMS) are non-updatable fields
The email field of Email contacts will not be overwritten

# Channel Import Restrictions

For the EDM and WhatsApp channels, imports have specific status fields and validation logic. Please be sure to follow them:

A. Email (EDM) contact import

Important import restrictions

To comply with international anti-spam regulations and protect domain reputation, MAAC has a strict "status irreversibility" rule:

🚫 You cannot change a contact whose status is "Unsubscribed" or "system-blocked" back to "Subscribed" via CSV import.

If the CSV attempts to change Unsubscribed to Subscribed, the system will ignore that status update and only update the other fields (such as name and phone). This prevents accidentally sending to mailboxes that have explicitly opted out or are invalid, avoiding your brand being blacklisted.

📌 Re-importing a previously deleted Email contact: if the address you import was previously deleted, the system reuses the suppression status that was kept from before deletion (unsubscribed, spam report, hard bounce) and applies that, ignoring the messaging_status in your CSV. In other words, re-importing does not make an unsubscribed or blocked address sendable again; the only way to restore sending is for the recipient themselves to re-subscribe. For deletion, see: Onboarding Guide | How to Enable Email Channels and Import Contacts

Automatic suspension mechanism (Suspension Policy)

To maintain the sending quality for all users, the system has an automatic monitoring mechanism. If your sending domain encounters the following situations, the system will automatically suspend your sending function:

Trigger conditions (within the past 24 hours):
- Hard Bounce: too many emails sent to non-existent mailboxes, exceeding 20 times and a bounce rate > 5%.
- Spam Report: too many users marking your emails as spam, exceeding 10 times and a report rate > 0.5%.
How to recover?
- You must first use a third-party tool to clean your Email list and exclude invalid entries.
- Import the cleaning results into MAAC to update the contact statuses.
- Notify your CSM to help apply for reinstatement; after manual review, it is manually restored from the back end.

⚠️ 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

To comply with Meta's technical specifications and ensure data validity, WhatsApp contact import has the following mandatory rules:

• The status field (Status) cannot be left emptyUnlike other channels, when importing a WhatsApp list, the status field in the CSV file is absolutely required.
Allowed values: opted_in (agreed), not_subscribed (not subscribed), opted_out (unsubscribed).
System behavior: if the status field of a record in the CSV is empty, the system will directly "Skip that record", without importing or updating it at all.

• Phone number format restrictionYou must use the E.164 international format (for example: +886912345678). If the format does not match, the system cannot create a valid WhatsApp contact, leading to a send failure.

Meta account quality and suspension mechanism (Quality & Suspension)

• Risk consequences: sending to users who have not consented (not_subscribed) or have unsubscribed (opted_out) very easily leads to blocking or reporting. This causes a drop in account quality rating, a downgrade of the daily quota, and in severe cases, WABA account suspension.

• System protection (Risk Acceptance): if your send recipients include the "not reachable" list above, MAAC will force a warning to pop up, and you must check the risk consent form before you can send.

# 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 that the field names and Key values are consistent, in order to avoid creating duplicate contacts.

Step 2: Upload the file

Upload the prepared CSV file. The system will automatically perform format validation and data matching.

Step 3: View the results

After the import is complete, you will receive a notification (the bell icon). If there is any failed data, the system will provide an "Import Failure Report" for download. Please make corrections according to the error reasons in the report (such as: format error, invalid domain, Status not filled in).

# Identity Integration and Conflict Handling After Import

After the import is complete, the system performs Identity Integration in the background, determining which contacts belong to the same person and unifying them into one Unified Contact based on the Unify Keys you have set. The entire process has two stages:

Import complete: the CSV list is created / updated, and you receive a notification (the bell icon).
Integration complete: the background Identity Integration completes the unification.

⚠️ Verify the unification result only after integration is complete
Because Identity Integration runs in the background, "Import complete" does not mean "Integration complete". Please wait a moment, and after integration is complete, return to the contact list or Unified Contact Profile to confirm whether the unification is correct.

When an Import Causes an Identity Conflict

If, during integration, multiple contacts that may be the same person are found to carry different Customer IDs, the system does not merge them automatically — to avoid incorrect merging — and marks them as an identity conflict. In this case:

When an identity conflict is detected, a ⚠️ indicator appears on the Export button in the contact list, meaning the conflict report is available for download.
You can also go to Export > Export conflict contacts in the contact list to download the list that is currently still in a conflict state.

Correct and re-trigger unification:

Download the conflict list and confirm whether the related contacts truly belong to the same person.
Correct the wrong Customer ID, or add the correct identifying data.
Re-import the corrected list, and the system will run Identity Integration again.

📌 Re-importing can also restore Identity Integration for a split contact
If a channel contact was manually "split" and had Identity Integration disabled, re-importing its correct identifying data will likewise re-trigger unification, and the split note will disappear after integration is complete. For details, see Tutorial | Unified Contact Profile and Splitting Contacts.

👉 To download the conflict list and for the CSV field descriptions: How to Export Contacts and the Data Mapping Table; for the conflict detection mechanism: Feature Description｜Contact Field Definitions and Matching Logic.

# FAQs

Q: If an imported phone has multiple duplicates in the system, which one will be updated?

A: The system will update the contact that was "created later". To avoid incorrect updates, we recommend using line_uid or customer_id as the matching basis instead.

Q: When importing tags, will the existing tags be overwritten?

A: No. Imported tags are automatically merged with existing tags; the system does not delete existing tags.

Q: Why were some fields not updated successfully?

A: Possible reasons are as follows:

The field was empty in the import file; the field name does not match the back-end settings; the field is a "channel primary key" and cannot be updated (line_uid, WhatsApp_mobile, email (EDM primary key), SMS phone); when using customer_id as the Key value, if that customer_id does not exist in the system, no new contact is created.

Q: When importing data, can I add and update contacts at the same time?

A: Yes. The system automatically determines whether each record is an update or a creation based on the Key value you select. However, if you use customer_id as the Key value, the system only updates existing contacts and does not create new contacts.

Q: Why were contacts merged after import?

A: MAAC automatically merges data according to the Profile Unification rules. As long as any of the following fields matches an existing contact, they will be merged into the same Profile: email, phone, customer_id, line_uid, WhatsApp_mobile, fb_id, ig_id.

Q: Why were some contacts not 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 incorrectly merging different people — and marks them as an identity conflict. Please download the conflict list, confirm whether they are the same person, correct the Customer ID or add the correct identifying data, then re-import, and the system will run the unification again.

Q: Why hasn't the unification result updated after the import is complete?

A: Identity Integration is a background process; the "Import complete" notification does not mean "Integration complete". Please wait a moment, and after the background integration is complete, return to the contact list or Unified Contact Profile to confirm the unification result.

Q: Why are some rows skipped during a WhatsApp import?

A: WA import requires two mandatory fields: WhatsApp_mobile and status. If status is empty (opted_in / opted_out / not_subscribed not filled in), the system skips that record and does not import it.

Q: I have already imported Email contacts, so why can I still not 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 sender conditions for the "Send Email" node in the journey to work properly.

Q: When importing custom fields, the system shows that the field cannot be found — how do I handle this?

A: Please check your CSV file header. The system requires custom fields to carry the cl_custom_ prefix; the correct format is cl_custom_{field identifier}. Please go to the Admin Center to confirm the spelling of the field identifier, and ensure the field status is "Active" rather than "Archived".

Q: What format requirements are there for imported custom field values?

A: Different field types have different format requirements:

Text: a free-form text string
Number: only numbers are accepted (may include a decimal point)
Date: only the YYYY-MM-DD format is accepted
DateTime: the YYYY-MM-DD HH:mm:ss format is accepted, and the system stores it as UTC+0