This article explains how customer and supplier contacts move between Qoblex and Xero: which Xero contacts are imported, how existing records are matched, and exactly which fields map in each direction. It applies to both the Import from Xero action on the Customers and Suppliers pages and to the contact details Qoblex sends to Xero when a document for that contact syncs.
Requires the Xero integration to be installed and connected.
Importing contacts from Xero (Xero → Qoblex)
Triggered from Contacts > Customers > Import > Import clients from Xero or Contacts > Suppliers > Import > Import suppliers from Xero.
Which Xero contacts are imported
Qoblex uses each Xero contact’s customer and supplier flags to decide what to import:
- A customer import brings in Xero contacts marked as a customer in Xero, plus contacts that are marked as neither a customer nor a supplier.
- A supplier import brings in Xero contacts marked as a supplier in Xero, plus contacts that are marked as neither.
So a Xero contact flagged only as a supplier is skipped during a customer import (and vice versa), while a contact with neither flag set is imported by both.
How existing contacts are matched
Each Xero contact is matched to an existing Qoblex contact by email address and the same type (customer or supplier):
- If a match is found, Qoblex updates that existing contact.
- If no match is found, Qoblex creates a new contact and defaults its Business Type to Retail.
Qoblex stores the Xero contact’s ID as the contact’s reference, so the contact links back to Xero and is not duplicated on later syncs.
Field mapping (Xero → Qoblex)
| Xero field | Qoblex field | Notes |
|---|---|---|
| Name | Company name | |
| First name + Last name | Contact person | Combined into one value |
| Email address | Also used to match existing contacts | |
| Website | Website | |
| Tax number | Tax Number | |
| Phone (type DDI) | Landline phone | |
| Phone (type MOBILE) | Mobile phone | |
| Phone (type FAX) | Fax | |
| Address line 1 / line 2 / city / postal code / region / country | Address line one / line two / city / zip code / state / country | Each Xero address becomes a Qoblex address |
| Contact ID | Reference to Xero | Stored to link the records and prevent duplicates |
Sending a contact to Xero (Qoblex → Xero)
When a Qoblex sales or purchase document for a contact syncs to Xero (for example an invoice or a bill), Qoblex first makes sure the contact exists in Xero so the document can be attached to it:
- If the contact already has a Xero reference, Qoblex links to that existing Xero contact by its ID and does not overwrite the contact’s details in Xero.
- If the contact has no Xero reference yet, Qoblex looks for a Xero contact with the same name. If one is found, Qoblex links to it; if not, Qoblex creates a new Xero contact from the fields below. Either way, the Xero contact’s ID is saved back on the Qoblex contact so later syncs reuse it.
If the saved reference points to a Xero contact that has since been archived in Xero, Qoblex removes the broken link, tells you the contact “was linked to an archived Xero contact. The link has been removed and the order will be reprocessed,” and reprocesses the document so the contact is linked or recreated.
Field mapping (Qoblex → Xero)
| Qoblex field | Xero field | Notes |
|---|---|---|
| Company name | Name | If the company name is blank, the email address is used as the name |
| Contact person | First name | |
| Email address | ||
| Tax Number | Tax number | Sent only when present |
| Landline phone | Phone (type DDI) | Sent only when present |
| Mobile phone | Phone (type MOBILE) | Sent only when present |
| Fax | Phone (type FAX) | Sent only when present |
| Addresses | Address (type PO BOX) | Line one/two, city, postal code, country |
What you see
- Imported and matched contacts show a reference to Xero on the contact record; the import report lists how many contacts were added versus how many already existed.
- When a document sync links or creates a contact in Xero, Qoblex shows a notification — “Customer” or “Supplier name synced to Xero” — with a View in Xero link to open the contact.
- Contacts created in Xero from a Qoblex document carry the same reference link, so the next sync reuses the Xero contact instead of creating a duplicate.
