Job xero-contact-duplicates-from-sync · revised 11 October 2026
Make a customer sync reuse the right Xero contact instead of creating near-duplicates
Replaying a synthetic customer list through one named sync creates each customer once in a Xero demo organisation, and a changed email or name updates the same contact.
You might be seeing
- Contacts that differ only by case, spacing, a changed email or a company suffix
- An invoice lands on a new contact when a customer updates their name or address in the shop
- A previously archived contact blocks the sync with a name or number error
No passwords, keys, card details or admin invites needed to start.
What usually happened
The sync decides whether a customer already exists by comparing a name or an email string, which changes or varies, rather than by a stored Xero contact identifier or a stable customer number of its own. Any change in the text, or a contact archived earlier, makes the sync create a new contact.
Who it’s for: An operations lead, bookkeeper or shop owner whose shop, CRM or spreadsheet pushes customers into Xero and who finds the same customer split across several contacts.
Usually starts when: Statements, aged receivables or invoice history for one customer are spread over contacts with slightly different names or emails, and every sync run adds more.
The result: A synthetic customer list run twice through the sync produces one Xero contact per customer, a customer whose name or email changes updates the same contact, and conflicts are listed for a person instead of creating another contact.
Check whether this job fits
Answer these from what you can see without sending logins, invoices or customer data. Nothing is submitted unless you choose to contact us; this is a fit check, not permission for us to touch your systems.
Checks you can run yourself
Look for contact groups that are really one customer
In Xero, sort contacts by name and look for neighbours that differ by case, punctuation or a suffix. Do not merge or archive anything yet.
Look for: Groups of two or more contacts for one customer, and whether they were created by the same connection. This shows whether the cause is the matching rule or several writers.
What you get
- The change as a pull request or exported configuration, with the match order written down in plain words
- A test log showing contact counts before and after each replay, redacted
- A list of suspected duplicate groups in your test data, or in a redacted export you provide after agreement
Included
- One named sync that creates or updates Xero contacts from one customer source
- A stable customer identity stored against the contact (the contact number the API allows, and the Xero contact id once known) and a match order that uses it first
- A rule for same-name customers with different ids, changed details, and archived contacts that hold a contact number
- A report of suspected existing duplicates by identity, as a list for your bookkeeper to merge or archive in Xero
- Replay and change tests on a Xero demo organisation with invented customers
Not included
- Merging, archiving or deleting contacts in your real organisation: your bookkeeper does that in Xero
- Changing how invoices are created, numbered or taxed
- Cleaning the customer source itself, or deciding which of two real customers is the right one
- Contact groups, payment terms or tracking set-up beyond the fields the sync already writes
- Bookkeeping, tax, audit or any accounting advice, including deciding how a transaction should be treated in your accounts
- Changing posted, reconciled or locked-period transactions: your accountant or account holder decides and performs those
- Live changes: your authorised account holder applies any agreed change and holds the production keys
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
A synthetic list of ten invented customers, replayed twice, leaves exactly ten contacts in the demo organisation with unchanged contact ids.
Evidence: The list, contact counts after each replay and the contact ids, redacted.
An invented customer whose email and name are changed in the source updates the same contact rather than creating another.
Evidence: Before and after contact record and the contact count.
Two invented customers with the same name and different ids follow the written rule: two contacts, or one held conflict, never silently one merged contact.
Evidence: The rule text, the resulting contacts or held list.
An invented archived contact holding a contact number produces a listed exception instead of a new contact.
Evidence: The setup note and the exception entry.
Sign-off. You inspect the named test evidence and sign off before payment. Your authorised account holder performs and verifies any live change, and decides what happens to records already posted.
If it fails. If an agreed check does not pass, you do not pay for this fixed scope. We hand over the findings and agree whether to stop or re-quote; no surprise work and no change to your live records.
When it fits, and when we stop
It fits when
- Each source customer has an id that is never reused, or one can be agreed as part of scope
- A Xero demo organisation can be used for synthetic contacts; no real customer is written during tests
- The sync can be run against the demo organisation, or its contact step exercised on its own
- Your bookkeeper agrees how suspected duplicates in the real organisation will be reviewed
- Real financial records, customer data and keys are handled only after written agreement, through a secure handoff we agree with you; the first enquiry and the fit check use invented or redacted examples
We stop and tell you if
- The source has no identifier that survives a name or email change and none can be agreed
- The sync must also push contacts into another accounting system with different matching rules
- Most of the problem is a large historical clean-up of contacts, which needs a separate agreement
What could go wrong
Before merge, closing the pull request leaves the sync unchanged. After merge, your developer can revert it; contacts the new rule created in the demo organisation are disposable, and your real contacts are not edited by this job.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| Two real customers are matched into one contact because they share a name or an email. | The stored identity is compared first, text comparison is only a flagged fallback, and the same-name case is a named acceptance test. |
| A contact number is written over one another integration already uses. | The job checks whether a contact number is already in use before assigning one and lists clashes instead of overwriting. |
| Tests create unwanted contacts in the live organisation. | Tests run only against the demo organisation, which Xero documents as resetting itself, and not against live data. |
An independent reviewer checks that matching really uses the stored identity first, that archived and same-name cases are handled by the written rule, and that the evidence contains only invented customers.
How we deliver
We arrange the work and independent review, then show you the result against the agreed checks. You keep authority over your systems.
- Agree the customer source, the identity rule and the contact number the sync will store in writing
- Reproduce the duplicates with invented customers on the demo organisation and record contact counts
- Store the identity against each contact and change the match order to use it before any text comparison
- Handle same-name pairs, changed details and archived contacts by the agreed rule, and list conflicts for a person
- Replay the invented list twice and a change set once, capturing counts and contact ids
- Independent review of the diff and the test evidence, then hand over for your developer to merge and your bookkeeper to review the real list
This is a one-off job, not emergency cover or a subscription. We confirm eligibility, the total price, a start window and a delivery date before you accept. Work starts only after agreed inputs, secure access, any licences and necessary permissions are in place. Platform and supplier charges are excluded unless the written quote includes them. No charge or booking is created by an enquiry.
Need to keep it working?
If customers change often, discuss a periodic duplicate-contact report as a separate agreement.
Ongoing work is separately scoped and quoted: no monitoring, response-time guarantee or automatic subscription is included in this job.
Explore an ongoing engineering lane, or mention the responsibility you need in your enquiry.
What you can check
This is a new service. We have not delivered this job for a client yet.
Other ways to get this done
- Xero's developer documentation explains the contact fields available for linking an external record, including a contact number that only the API can change. developer.xero.com
- Your bookkeeper can merge duplicate contacts inside Xero without us; this job stops the sync from creating more.
Questions
Will you merge my existing duplicate contacts?
No. Merging or archiving real contacts is done by your bookkeeper in Xero. We give a list of suspected groups to speed that up.
Why not match on email?
Emails change and are sometimes shared by several customers. A stored identity is a safer first key; email can still be a flagged fallback.
Does this work for QuickBooks Online?
This job is for Xero. QuickBooks Online has different customer naming rules and would be scoped separately.
Send an enquiry
Send us
- How the sync decides today whether a customer exists (name, email, something else) in your own words
- Three invented customers that show your problem, for example a changed email and a same-name pair
- Whether archived contacts are common and whether contact numbers are used in Xero today
- Do not send credentials, bank details, invoices, customer records or confidential code in the first enquiry
Later, once you agree
- Read access to the sync definition or code through the agreed route, with secrets held by you
- A Xero demo organisation connected by you for the job
- A redacted or synthetic contact export if you want the suspected-duplicate list produced from real structure
- A secure, company-controlled handoff route agreed in writing before any access; no passwords, keys or customer records by ordinary email
You keep the live accounting organisation, payment accounts, production keys and every customer and financial record. We work on an authorised demo, sandbox or synthetic copy through a company-controlled handoff, never a personal login. Your authorised account holder approves and performs any live change and checks the result under their own keys.
Email fallback: open your mail app
If website submission is unavailable, review and send the fallback email yourself. An email fallback is not a website receipt. Or write to hello@syntheticindustry.ai with “xero-contact-duplicates-from-sync” as the subject.