In Appmint, customers and contacts are the same record type (customer). A contact is a customer with accountType: "contact": no password, no sign-in, nothing sent to them. That is what this job makes. A person who must sign in to the site needs a real account, and making one emails them a welcome (see Stop in step 2).
For a group worked out by rules ("everyone in Texas", "everyone tagged vip"), make a smart group instead: Broadcast audience from a filter. For one customer on the phone, see Phone order for a customer.
Ask first
- The people. A file (CSV or Excel) or a pasted list. At least an email for each; a name, phone and company where known.
- Which group? An existing one by name, or a new one with a name and a line on who is in it.
- Tags? The words, spelled once (e.g.
wholesale). - Do they need to sign in? If yes, each needs a real account, which emails them. If no (the usual case: a mailing list, a trade list), they are contacts.
Steps
1. Customers & Benefits: who is already there
For each email, lowercase it and look it up: find_records on customer with { "data.email": { "$regex": "^<email>$", "$options": "i" } } (escape any ., + in the address). Also look up by phone when there is no email.
Make three lists: already a customer (with their sk), new, and can't add (no email and no phone, or the same person twice in the file).
The duplicate check on a new contact compares the exact text. [email protected] and [email protected] become two contacts. Always lowercase emails, and always look up first.
Hands on: the three lists; the sks of the people already there. Check: read the counts back to the person ("41 new, 9 already customers, 2 with no email"). If someone could be two existing records, ask which.
2. Customers & Benefits: the new contacts
For each new person, call_appengine PUT /repository/create with:
{ "datatype": "customer", "isNew": true,
"data": { "accountType": "contact", "email": "<lowercased>", "username": "<the same email>",
"name": "<full name>", "firstName": "…", "lastName": "…", "phone": "…", "company": "…",
"status": "active", "source": "<where the list came from, e.g. import:trade-show-2026>" } }It saves the contact and sends nothing. A repeat is refused with 409 { "reason": "duplicate", "error": "A customer with email \"…\" already exists." }: count it as already there, don't retry.
For a file the person wants to load themselves: Customers & Benefits → Contacts → Import (/customers-benefits?view=contacts) takes .csv, .xlsx or .xls, maps the columns, skips rows whose email is already a contact, and can put everyone in a group. Its Create mode sends nothing.
create_recordoncustomergoes through customer sign-up, which emails each person a welcome. Don't use it for this job.- The Import screen's Update and Merge modes save each matched customer, and every customer save emails that customer that their profile changed. Use Create.
- The general data import (Import records into a collection) refuses customers.
Stop: only if they must sign in. A real account is POST /profile/customer/signup with { email, firstName, lastName, phone } per person, and each one is emailed a welcome at once. Show the list and the count, and wait for yes.
Hands on: the new contacts' sks, plus the sks from step 1.
Check: open one or two (/customers-benefits?openId=<sk>): the email and name are right.
3. Customers & Benefits: the group
Find the group (find_records on customer_group by data.name). If there is none, create it with create_record on customer_group: { "name": "<name>", "description": "<who is in it>", "groupType": "static", "contacts": [] }.
Add everyone: call_appengine POST /crm/customer-groups/members with
{ "customerIds": ["<sk>", "<sk>"], "add": ["<group sk>"] }It answers { "customers": 2, "changed": 2, "added": ["<group name>"], "removed": [] }. It puts each person in the group's contacts and the group's name in their own groups, keeps their other groups, and emails nobody. "remove": ["<group sk>"] takes people out. Send up to a few hundred ids per call.
A smart group (groupType: "dynamic") refuses this with 409 dynamic_group: its rules decide who is in it.
Hands on: the group's sk.
Check: GET /crm/customer-groups/counts gives { "<group sk>": <members> }, and POST /crm/customer-groups/match with { "groupId": "<group sk>" } lists them. Open the group at /customers-benefits?view=groups&groupId=<sk>.
4. Customers & Benefits: the tags
call_appengine POST /crm/contacts/bulk with
{ "customerIds": ["<sk>", "…"], "action": "add_tags", "tags": ["wholesale"] }Up to 1,000 ids a call. It answers { "action": "add_tags", "done": 2, "failed": [] } and emails nobody. A tag a contact already has, in any case, isn't added again. "action": "remove_tags" removes them (also in any case).
Hands on: the tags.
Check: a contact's data.tags lists them (/customers-benefits?openId=<sk>).
When it's done
Tell the person:
- how many contacts were made, how many were already customers, and who couldn't be added and why;
- the group, its member count, and that nobody was emailed;
- the tags.
Open the group.
What it can't do yet
- No duplicate check by case. Two contacts can share an email in different case (step 1).
- Changing an existing customer's details emails them. Name, phone or company on a customer already there can't be updated quietly; every customer save sends the "profile updated" email. Leave existing customers as they are unless the person accepts that.
- The same tag can be stored twice if one request sends two spellings (
vipandVIP). Send one spelling. - Notes. Studio's contact panel has no Notes tab, and the customer 360 view doesn't show notes.
POST /notes/customer/<sk>with{ "comment": "…" }saves one on the record, but nobody sees it on screen.
Don'ts
- Don't create customers with
create_recordor/profile/customer/signupunless they must sign in and the person said yes. - Don't put a group's name in a customer's
groupsby saving the customer; use the members call. - Don't add people the person didn't name, and don't guess an email.
- Don't delete contacts to "clean up":
POST /crm/contacts/bulkwithdeleteemails each one that their account was removed.