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.
The import dialog also notes a Xero-side condition on which contacts appear:
Xero contacts are identified as customers only and only if they have invoices or credit note transactions attached to them.
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 | Qoblex reads the Xero landline (DDI) number into Landline phone |
| Phone (type DDI) | Mobile phone | Qoblex fills Mobile phone from the Xero landline (DDI) number, not from the Xero MOBILE entry. It is populated only when the Xero contact has a MOBILE phone entry, and even then the value copied in is the landline (DDI) number |
| Phone (type DDI) | Fax | Qoblex fills Fax from the Xero landline (DDI) number, not from the Xero FAX entry. It is populated only when the Xero contact has a FAX phone entry, and even then the value copied in is the landline (DDI) number |
| 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 |
This is how Qoblex currently imports these numbers: the Landline phone, Mobile phone, and Fax fields are all filled from the Xero landline (DDI) number. The numbers stored under Xero’s MOBILE and FAX phone types are not read during import.
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 is no longer available in Xero (for example it has been removed or can no longer be found), Qoblex removes the broken link, tells you the contact “was linked to a Xero contact that is no longer available. 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 View this contact in Xero link on the contact record; the import report lists how many contacts were added versus how many already existed, with lines such as “Added {n} new contacts from Xero” and “Found {n} contacts which already exist in Stock&Buy”.
- 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.