How JomeInvoice matches buyers and suppliers
Last reviewed: 2026-07-31 · Last updated: 2026-08-07
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: Corrected the name of the settings screen so it matches what you see in JomeInvoice.
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.
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 |
New workspaces start with Name, TIN, and Registration Number selected. You can change the selection at any time, and it applies to your whole workspace.
Switching on more identifiers makes matching stricter, not more likely to succeed. Every identifier you select 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.
Matching is also an exact comparison against the values saved in JomeInvoice, and it does not look the TIN up with LHDN at this point. 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.
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 |
If even one of these is missing, no record is created and the document fails instead. JomeInvoice does not create a partial record.
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. Those are the same details used to find the record in the first place.
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.
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 reliably sends for every buyer, and remember that each extra identifier you select is one more value that has to match exactly.
You can review both settings in Workspace Settings, under General. Contact JomeInvoice if you want help choosing the right combination.