Prerequisites:
Before getting started, ensure you have:
Required Permissions:
The Bulk Import feature is available to staff members with the following permissions:
Owner
The file imported into AIQ must:
Have only one tab
Be a .csv or .xlsx file
How to Import Personas
Navigate to Customers > Personas and click Add (+)
Click the button "Bulk Import Personas"
Here you can see which column headers you can use in your file.
Click All Headers to see all possible column headers
Click Upload File and select your import file
Review each column mapping to confirm it is correct. Automatically mapped columns will be marked with a checkmark.
Unmapped columns will be marked with an "X". If a column isn't mapped:
In the Property column, click the property dropdown and select the appropriate field.
Repeat for other unmapped columns as necessary.
Click the checkbox under the Ignore column to prevent that row from being imported entirely.
Once all column mappings are addressed, click Next.
On the Upload Details page you can customize the name of the import. There will also be an estimate of how many personas will be uploaded and how many fields have been mapped.
Import Options:
Opt-in all imported personas to email if turned on will override any opt in status provided within your import file and sets all personas included optin statuses to True.
Opt-in all imported personas to SMS if turned on will override any opt in status provided within your import file and sets all Personas included optin statuses to True. Only Personas with a valid mapped mobile or home phone number will be opted in — Personas with missing or unmapped phone numbers are skipped.
Agree to Alpine persona terms (required for import)
Click Import Personas
ℹ️ The "Opt-in all imported personas to SMS" toggle performs a direct opt-in — it does not send a double opt-in confirmation message to shoppers. All personas in the file will be immediately opted in to SMS. Only use this toggle if you have confirmed prior consent for all contacts in the file. Any Persona without a valid phone number will be skipped.
View Import History
In order to see import history, or previous files you've uploaded:
Navigate to Customers > Personas
Click on the more (...) icon in the top right corner of the personas table
Click on "View Import History"
To re-download the CSV or view the file import as an audience:
Navigate to "View Import History"
Click on a file (row) in the table
Click on the more (...) icon
Click on "Download CSV" or "View Audience"
Import Examples
Below are common examples of how file uploads can be used to import and update Personas in AIQ. Sample CSV files for each template are attached at the bottom of this article.
Import Persona Templates
Use this template to import shoppers from a previous loyalty or marketing provider.
Sample file:
See the aiq-import-normal.csv attachment at the bottom of this article.
Set SMS Opt-In and Opt-Out Statuses
Use this template to manage SMS consent statuses for existing or new Personas.
Sample file: See the aiq-import-sms-statuses.csv attachment at the bottom of this article.
Example behavior:
[email protected] is currently opted in but needs to be opted out. Set the Explicit SMS Opt-out column to
TRUE.[email protected] and [email protected] already exist in AIQ but are not opted in. Use the Opt-in SMS column to opt them in and ignore the Explicit SMS Opt-out column.
Important notes:
Ensure you have proper consent before opting shoppers in to SMS.
Only Personas included in the file will have their SMS opt-in or opt-out status updated.
Add or Subtract Loyalty Points
⚠️ Important: The Points field is additive — it adds to or subtracts from a shopper's existing balance. It does not set an absolute balance. If you upload a "current balance" CSV, those values will be added on top of whatever balance already exists, which can result in significant over-application.
⚠️ Negative point uploads aren't supported in FIFO.
To reduce points in bulk, use negative manual adjustments (limited to each shopper's current balance) or a zero points audience to reduce points from sales.
Use this template to adjust loyalty point balances in bulk.
Sample file:
See the aiq-import-points.csv attachment at the bottom of this article.
How it works:
The Points column adds to or subtracts from a Persona’s existing balance.
This upload does not overwrite or set the total point balance.
Example behavior:
[email protected] will have 200 points subtracted
[email protected] will have 50 points added
[email protected] remains unaffected
Set Customer Type (Veteran, Police, Locals, etc.)
Use this template to assign customer types or special attributes.
Sample file:
See the aiq-import-customer-type.csv attachment at the bottom of this article.
How it works:
The Customer Type column is reserved for medical and recreational statuses.
Use Custom Attribute columns for all other customer types (for example, veteran or police).
Set custom attributes to
TRUEto apply them to the Persona.
Troubleshooting
Why are my imported points showing as "Legacy imported points" and not appearing in the wallet?
Loyalty must be enabled in your settings before imported points become wallet-redeemable. If you imported points before enabling loyalty, go to Settings > Loyalty and ensure loyalty is turned on with a start date set. Once enabled, imported points will become redeemable.
Bulk Import FAQs
How do I ensure I'm not creating duplicate personas on upload?
We match on phone or email, so a phone or email must be included in your file upload to address duplicate personas.
If your uploaded shopper file is missing key identifiers (like email or phone number), AIQ can’t match records to existing Personas—so it counts them as new signups.
Fix it:
Include at least one unique identifier (email or phone) per record
Double-check data quality before upload
This ensures accurate reporting and prevents duplicate Personas.
⚠️ Warning: If your file contains duplicate records that share the same phone number or email, AIQ will merge those records on import and combine the points from each duplicate — which can result in significant over-application. Always deduplicate your file before uploading.
How long do persona imports take to make changes?
Imports take 24 hours to process. File deletions also take 24 hours to process. Generated audiences are not populated for the 24 hours.
Why does my Persona's Favorite Store show [Store Name]:::rawfiles after import?
The :::rawfiles suffix is a source tag, not an error flag. It means the Favorite Store value was set via a file import (CSV or XLSX) — rawfiles is AIQ's internal name for the File Import integration. This tag is expected on any file-imported Persona and does not indicate a problem with the import itself.
What it signals is that the raw store name string in your import file isn't yet mapped to a Retail Location in AIQ. Until a mapping exists, AIQ preserves the raw string with the source tag instead of resolving it to the location name.
ℹ️ To resolve the display, add a Loyalty Mapping entry in Settings that maps your raw store name string (for example, "A Little Bud White Rock (1)") to the correct Retail Location. Once the mapping exists, future imports using that same string will resolve correctly. Alternatively, update your import file to use the exact store name string already configured in your source mapping.
Does the Points column in my spreadsheet add/subtract points to the persona's balance OR does it set the balance to the number in the spreadsheet?
It adds/subtracts points. It does NOT set the total balance.
If a retailer uploads a list of shopper data and the data for that shopper is different than whats getting pulled in from the POS, would the manual upload override the POS data?
Not by default. In general, the first value AIQ receives for a given shopper attribute is the value that “wins” and is retained on the shopper’s persona. A manual upload won’t overwrite POS-synced data automatically.
The exception is when the upload includes an explicit override field. For example, if the retailer includes a Signup Override Date column, that override value will take precedence over the existing signup date. If no override field is provided, the shopper’s original signup date remains the signup date on their persona.
⚠️ Sign-up date is tied to loyalty enrollment, not persona creation. The sign-up date field is only populated when a shopper enrolls in the loyalty program (via a signup form, POS checkout, or a loyalty opt-in event). If a Persona is created through a POS integration that does not pass a loyalty enrollment event — such as a first purchase sync without an opt-in — no sign-up date will be generated, and the field will remain blank (N/A). This is expected behavior, not a configuration issue. The sign-up date will only appear once the shopper has an actual loyalty enrollment on record.
Do I need to add a "loyalty status:true/false" column?
You can add a “loyalty” column, but it’s not needed since the system will auto-enroll any Persona that is having points added to it.
If there is a points balance not equal to 0 (zero), or a text opt-in value set to true on ANY persona within the file, they will automatically be opted into loyalty as well.
Additionally, setting loyalty = false, does not opt out the personas from loyalty if they are currently a loyalty member.
If I upload a file without names (only phone and/or email), can we still import their loyalty points?
Yes, we just need phone and/or email to create persona and import their points.
Need Help?
If you need help with your bulk import please reach out to AIQ Support through the chat widget in your dashboard.