How JomeInvoice matches buyers and suppliers
Last reviewed: 2026-07-31 · Last updated: 2026-08-14
Scope: How the matching identifiers and auto registration settings decide whether an incoming invoice links to a saved Customer or Supplier, creates a new record, updates one, or stops for review, across automated feed, API, and Bulk Upload.
Update: Explained that an email address is required for customers and suppliers, and corrected how selecting matching identifiers affects the search.
Every time a document reaches JomeInvoice with buyer or supplier details on it, JomeInvoice answers two questions, in this order:
- Matching: do we already have a saved record for this buyer or supplier?
- Automatic registration: if we do not, should a record be created?
Matching only searches. Automatic registration decides what to do with the search result. Keeping the two steps separate is the fastest way to work out why a document did not link to the customer you expected.
This applies to Customers (your buyers) and Suppliers (your vendors) in the same way, and to every way an invoice or receipt can reach JomeInvoice: an automated (SFTP) feed, the API, and Bulk Upload.
Both steps are controlled by two settings in Settings → Workspace Settings, under General:
- SFTP & API Customer/Supplier Matching Identifiers, which controls step 1.
- Customer/Supplier Auto Registration, which controls step 2.
These settings are named for SFTP and API, but they also govern invoices you add through Bulk Upload. Changing them affects all three routes.
They apply to records reached through an incoming document. Adding a customer by hand, inviting one to self-onboard, or uploading a customer list by CSV follows its own rules and is unaffected by these two settings.
Step 1: matching
JomeInvoice compares the buyer or supplier details on the incoming document against the records already saved in your workspace. There are three possible outcomes.
| Outcome | What it means | What happens next |
|---|---|---|
| One match | Exactly one saved record matches | The document is linked to that record |
| No match | No saved record matches | Automatic registration decides whether to create one |
| More than one match | Two or more saved records match | The document fails for you to review. JomeInvoice never guesses which record to use |
Matching never creates a record and never changes one. Its only job is to find, or fail to find, a safe existing match.
Which details are compared
You choose these under SFTP & API Customer/Supplier Matching Identifiers. Switch on the details JomeInvoice should compare:
| Identifier | Notes |
|---|---|
| Name | Always used. It cannot be switched off |
| TIN | The buyer or supplier Tax Identification Number |
| Registration Number | A business registration number, NRIC, or passport number |
| Registration Type | Which kind of registration number is being used |
| Customer Code | The customer or vendor code you maintain |
| Can be used only while Customer/Supplier Auto Registration is Disabled |
Open the setting to see which details are selected for your workspace. You can change the selection at any time, and it applies to your whole workspace.
Selecting more identifiers makes matching stricter only for the details your document actually carries. Every identifier you select and send has to match, so a record that matches on name and TIN will still fail if you have also selected Registration Number and the saved value differs.
If a document leaves a selected identifier out, or sends it blank, JomeInvoice leaves that detail out of the comparison and matches on the rest. This makes the search broader, not stricter, and it is the most common reason a document ends up matching more than one record.
The practical rule: send every identifier you have switched on, on every document. A detail you send inconsistently causes more trouble than one you do not select at all.
Matching compares the values saved in JomeInvoice, and it does not look the TIN up with LHDN at this point. Capitalisation is ignored when comparing the name, but every other detail must match exactly — a saved value that differs by a single space, a full stop, or an older registration number format will not match.
One more consequence is worth knowing: if the incoming document carries no buyer name, matching cannot run at all, so the result is always "no match", even when the TIN and registration number are correct.
Step 2: automatic registration
Customer/Supplier Auto Registration decides what happens to the matching result. It allows incoming invoices to create new customer or supplier records when no existing record matches.
Set it to Disabled and no record is ever created. Unmatched documents wait for you to review.
Automatic registration is Enabled by default, set to Insert. If nobody has opened this setting, incoming documents can already be creating customer and supplier records. Check it before your first automated feed or API submission goes live.
Set it to Enabled and a further choice appears, Insert or Upsert. Both create a new record when nothing matches. They differ in what happens to a record that does match:
| Choice | What JomeInvoice does |
|---|---|
| Insert | Use existing customer/supplier data without updating it. Will create a new record if no existing record matches |
| Upsert | Update existing customer/supplier data using the latest invoice payload. Will create a new record if no existing record matches |
That gives three behaviours in practice.
| Setting | When no record matches | When one record matches |
|---|---|---|
| Disabled | Nothing is created. The document fails for you to review | The saved record is used, unchanged |
| Enabled, Insert | A new record is created, if the document carries every required detail | The saved record is used, unchanged |
| Enabled, Upsert | A new record is created, if the document carries every required detail | The saved record is used, and its details are refreshed from the document |
What a new record needs
A record can be created automatically only when the incoming document carries all of these details:
| Detail | Why it is needed |
|---|---|
| Name | Makes the record findable and usable by your team |
| Registration type | States which kind of legal identifier is being used |
| Registration number | Ties the record to a legal or official identifier |
| TIN | Ties the record to a tax identity for e-invoicing |
| Gives the record a contact point, and is the address JomeInvoice sends invitations and notifications to |
If even one of these is missing, no record is created and the document fails instead. JomeInvoice does not create a partial record. A blank or empty value counts as missing.
Email is required by JomeInvoice even though LHDN does not require it. LHDN treats the buyer and supplier email address as optional, so a source system that follows the LHDN specification may not send one. JomeInvoice still needs it, for two reasons:
- A record cannot be created automatically without it, as above.
- A customer or supplier with no email address cannot be used on a document you submit to LHDN, however that record was created.
The second point matters even if you never use automatic registration. Records you add by hand or by Bulk Upload can be saved without an email address, and they will then stop a submission later. If a document fails on a customer that imported without any trouble, check that the customer has an email address saved.
Before switching automatic registration on, confirm your source system sends an email address for every buyer or supplier that may need to be created.
Email is not the only detail that behaves this way. The address matters just as much, and for the same reason.
These five details create the record. They are not enough to submit an invoice for it.
A document you send to LHDN also needs the customer's state and country. Neither is checked when the record is created, and neither is filled in for you.
So a record created automatically from a document that carried no address saves without complaint, and then every invoice for that customer fails at submission instead, with a message that the state or country does not exist. The cause and the symptom are far apart, which makes this one hard to recognise.
Send full address details, including country, for every buyer or supplier that may need to be created. If you already have records failing this way, open each one and add the missing address details.
What Upsert can and cannot change
Upsert refreshes a matched record from the invoice, but it never changes the details that identify the buyer or supplier.
Never overwritten:
| Detail | Why it is protected |
|---|---|
| Name | The saved record keeps the name your team gave it |
| TIN | Tax identity |
| Registration Number | Legal identity |
| Registration Type | Legal identity |
May be refreshed from the invoice: contact details, addresses, your customer or vendor code, and business attributes such as entity type, MSIC code, SST, and tourism tax.
This means Upsert cannot quietly rename a customer you already have, and it cannot change their tax or registration identity.
Customer Code is the one detail that appears on both lists. You can match on it, and Upsert is also allowed to refresh it. If you match on Customer Code, an invoice carrying a different code will change the saved code, and the next invoice using the old code will no longer match that record. Either keep the code stable in your source system, or do not use it as a matching identifier.
For everything else Upsert may change, decide deliberately whether the invoice or your team owns the detail.
For the details Upsert is allowed to change, the invoice becomes the source of truth, so a mistake in a file can overwrite good data in JomeInvoice. If your team maintains addresses or contact details inside JomeInvoice, choose Insert instead.
This includes the email address. The address on the invoice becomes the record's primary contact, replacing the one saved before it, and later e-invoice emails go to the new one. If your team has set a specific billing or accounts-payable address on a customer, an invoice carrying a different address will replace it.
Why more than one match always fails
When two or more saved records match, JomeInvoice stops and marks the document Failed.
It does not create another record, because that would add a further duplicate. It does not pick one of the matches either, because that would be a guess, and a wrong guess would attach the document to the wrong buyer.
The fix is to make your records unambiguous: keep one correct record per buyer or supplier, and correct or remove the duplicates. See Fixing buyer not matched errors.
Outcome summary
| Auto Registration | One match | No match | More than one match |
|---|---|---|---|
| Disabled | Uses the saved record | Failed, for you to review | Failed, for you to review |
| Enabled, Insert | Uses the saved record | Creates a record when every required detail is present, otherwise Failed | Failed, for you to review |
| Enabled, Upsert | Uses the saved record and refreshes its details | Creates a record when every required detail is present, otherwise Failed | Failed, for you to review |
Choosing your settings
Both settings apply to your whole workspace, and Customers and Suppliers share them.
| If this is true for you | Consider |
|---|---|
| JomeInvoice holds your master customer list, and you want to approve every new record | Disabled, so unmatched documents wait for you instead of creating records |
| Your source system holds the master list, and its data is reliable | Enabled with Upsert, so saved records are also kept current from the file |
| Your source system should create records but not change the ones you maintain | Enabled with Insert |
| You are rolling out a new feed and want to see the problems first | Disabled, or Enabled with Insert, so you can watch what fails before automating more |
For the identifiers, start with the details your source system sends for every buyer, on every document. Each identifier you select is one more value that has to match exactly when it is sent — and one more value that widens the search when it is not.
You can review both settings in Workspace Settings, under General. Contact JomeInvoice if you want help choosing the right combination.