docs
/
AI skills

Add or import customers and put them in a group

Bring a list of people into the CRM as contacts without emailing them, skip the ones already there, put them in a customer group and tag them, and check the group's count.

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_record on customer goes 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 (vip and VIP). 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_record or /profile/customer/signup unless they must sign in and the person said yes.
  • Don't put a group's name in a customer's groups by 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/bulk with delete emails each one that their account was removed.