Handling Contacts

This course is for anyone who takes orders, processes online orders, or touches a customer record in HubSpot. It explains one idea, one customer, one number, why the systems keep breaking that idea today, and what a small new piece of APSync does about it: mostly automatically, and sometimes by asking you a question.

Nothing described here has run against the real HubSpot yet. It is being shown to you first as a proof of concept on the AP Test portal, with made-up email addresses, so you can see what it does and change the rules before it touches anything real.

Why this comes up at all

You have probably seen one of these:

• You press Revise Invoice on a web order and get an error that says the contact has no customer number.
• The same person shows up in HubSpot twice, under two email addresses, and you are not sure which one to use.
• A customer number gets typed onto a HubSpot contact by hand the day after the order is keyed into MOM, and until then the invoice cannot be finished.

None of these are mistakes anyone made. They are what happens when three systems that each keep customers differently are asked to agree.

One customer, one number

Here is the whole model in three sentences.

1. A customer is someone (or an organisation) we can bill. Every customer has exactly one customer number, and no two customers share one. Two people at the same agency who both order are two customers with two numbers; what they share is the company, not the number.
2. A customer can have several ways to be reached: more than one email address over the years, a work phone and a mobile. All of them belong to that one customer. A new email address is not a new customer.
3. A customer can have several addresses, each with a job: where the bill goes, where the box goes.

flowchart LR
  C["Customer<br/>customer number 265189<br/>Heather Strang"]
  E1["email<br/>heather@agency.org"]
  E2["email<br/>hstrang@gmail.com"]
  P1["phone<br/>555-0142"]
  A1["billing address<br/>12 Main St"]
  A2["shipping address<br/>Program site, Bldg B"]
  C --- E1
  C --- E2
  C --- P1
  C --- A1
  C --- A2

That is it. Everything else in this course is about the gap between this picture and how each system stores it.

How each system sees a customer today

MOM gives a customer number to every record it makes, and it makes a record for a lot of things that are not customers: a second shipping address gets its own number, a person we once shipped to on someone else's order gets their own number, a catalog request gets one. So MOM has about 144,000 customer records for roughly 62,000 customers who have ever placed an order. When two of those records share an email, MOM cannot tell you whether that is one person with two addresses or two people at one email address.

HubSpot knows a contact by its email address, and only by that. If a customer checks out under a second address, HubSpot makes a second contact; it has no way to know they are the same person. HubSpot cannot be changed to match on name, and its support has confirmed that in writing. It also does not mint customer numbers; the number is a field someone has to fill.

The website knows a buyer by their login email. It has no idea what a customer number is, and it never will.

And the people. Each of us has been carrying one piece of the real model in our head: "number first, then email" is the right order of keys; "type the number the day after the order" is the matching being done by a person; "HubSpot should catch that duplicate" is true for an email HubSpot has already seen and false for a new one. All three are right about part of it. The point of this work is to write the whole thing down once, and have the system carry it.

What has actually been happening

When a web order comes in from someone HubSpot has not seen under that email, HubSpot creates a contact with no customer number. APSync needs that number to build the invoice, so Revise Invoice stops and says so. Meanwhile HubSpot's own sync sends the unfinished invoice to QuickBooks anyway, with only the product lines, and that failure shows up nowhere. The fix, until now, has been a person typing the number in after the order is keyed into MOM.

Measured on the real data on 2026-09-12:

• Of 37 invoices created on the live portal since late August, 22 had a contact with no customer number.
• Of 2,733 people who have ever bought on the website, 1,589 are already MOM customers by email but their HubSpot contact has no number. They are one automatic step away. About 360 are genuinely new buyers MOM has never seen.
• HubSpot holds roughly 450 clusters of "same person, two emails" that can be found with confidence, and about 1,200 same-name pairs that only a person could confirm.

What the new piece does

APSync now has a resolver. Think of it as the person who used to type the numbers, except it runs every time, remembers every answer, and only asks a human when it should. It does three things, in this order.

First, it clears the backlog, mostly by itself. Against the real data this means roughly:

Second, it asks a person about the rest. About 730 cases where two records might be one person, or one record might be two people, and only someone who knows the customers can say. Those go to a page in APSync called Contact cases, one question each, with three buttons. See How to resolve contact cases. Your answer is kept forever; the resolver never asks the same question twice.

Third, it keeps doing this as new contacts arrive. A new web order under a known email gets its number stamped. A new order from a known customer under a new email gets merged into their existing contact; the new email becomes a second address on that contact, and the old one is not overwritten. A genuinely new customer gets a new number, minted by APSync after the resolver has confirmed nobody matches. Only the ambiguous ones reach a person.

What it never does: delete a contact, invent a number for someone who might already have one, overwrite an email, change MOM, or touch a record that is not part of a case.

What this means for you

If you take orders (Sales)

• Search HubSpot before creating a contact. If the customer might already exist under another email, ask them; one email per person is the single biggest thing that keeps duplicates from forming.
• Stop typing customer numbers onto contacts once the resolver is live. If a contact has no number, it is either about to get one or it is on the cases page.
• When you see two contacts for one person, do not delete either. Either leave it for the resolver or use HubSpot's merge; merges keep history, deletes lose it.

If you process online orders (Ops)

• If Revise Invoice says the contact is not resolved yet, check the Contact cases page before doing anything else. If the contact is there, answer the case; if it is not, the next resolver run will handle it.
• Do not finish an invoice by hand for a contact with no number. That is the path that has been producing incomplete invoices in QuickBooks.

If you are asked to resolve cases

• Read How to resolve contact cases once. Then it is: look at the records side by side, pick a survivor or say they are different people, and move on. When in doubt, "different people" is the safe answer; it can be undone, a wrong merge is harder.

What you will see in the proof of concept

• It runs on the AP Test portal, not the real one.
• Every email address in it is made up on purpose, so nothing real lands in a test system. Names and companies are real so you can recognise the cases.
• The Contact cases page will have the real backlog of questions in it. Answer a few; that is the point.
• The rules above (who counts as a customer, when a number is born, which email is primary, what happens to a shared email address) are the ones we think are right. If you want them changed, this is the moment. Nothing runs against the real portal until the rules are agreed.

The decisions we still need from the business

1. When is a number born for a brand-new web buyer: at their first order, or as soon as they register?
2. Two people ordering through one shared email address: HubSpot can only give the email to one contact. Which one, and does the other get a contact at all?
3. Which email is primary for a customer with several: the one most recently used to buy, or something else?
4. After a "same person" decision, what happens to the losing number in MOM?
5. The 36,000 website logins that never bought: keep them in HubSpot, mark them, or archive them?

Words used here

• Customer number — the one identifier for a billable customer. Comes from MOM today; from APSync after the changeover. Never shared, never reused.
• Contact — HubSpot's record for a person. Keyed by email. One contact can carry several emails: one primary and the rest as "additional emails."
• Merge — HubSpot folding two contacts into one. Keeps deals, notes and emails from both. Can be undone for a while afterwards.
• Case — one question the resolver could not answer by itself, shown on the Contact cases page.
• Recipient — someone MOM only ever shipped to on another customer's order. Not a customer; never merged into the buyer.
• Resolver — the part of APSync that matches new and existing contacts to customers, stamps numbers, merges duplicates, and raises cases.