curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/matches \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"fields": {
"email": "[email protected]"
},
"kind": "customer",
"name": "ACME, Inc."
}
'{
"candidates": [
{
"full_name": "Acme Inc",
"is_active": true,
"list": "customer",
"list_id": "80000011-1712345678",
"reasons": [
"same after removing punctuation and suffixes"
],
"score": 1
},
{
"full_name": "Acme LLC",
"is_active": false,
"list": "customer",
"list_id": "80000012-1712345678",
"reasons": [
"same after removing punctuation and suffixes"
],
"score": 1
}
],
"candidates_total": 2,
"candidates_total_complete": true,
"index": {
"as_of": "2026-10-11T14:02:10Z",
"state": "ready"
},
"match": "candidates",
"record": null
}Match a name
Finds the records in the connection’s company file a name could mean, ranked, from QuBe Sync’s index of the file’s names (the connection’s name_index). QuickBooks itself only looks a name up exactly, or by “contains” on one list at a time. A match also ignores case, accents, punctuation, company suffixes such as Inc and LLC, spacing and word order, ranks near matches, and can compare an account number, email, phone, city and postal code. It’s answered at once, from the index as it stands: index.as_of says how current that is.
match is the first tier that applies: exact, strong, candidates or none (see the response). Use an exact match as it is, and confirm anything else with a person, or with what your app knows. A strong match is likely, not certain: Acme Inc and Acme LLC are strong for each other. Inactive records are matched too, with is_active: false.
Numbers in names count: Subway #1235 is never offered for Subway #1234, and Subway Store 1234 finds Subway #1234. In a file of near-identical names, such as numbered locations, candidates_total says how many records qualified: when that’s more than a person can choose from, ask for what tells them apart (the number, a city, a postal code, an account number) and match again with it. exact_only answers only exact or none, and min_score moves the candidate threshold for one call.
Match a record once. When it’s confirmed, keep its list_id on your own record and refer to it by that from then on (customer_ref: {list_id}): a list_id survives renames. Match again only when a stored list_id stops working, because the record was deleted or merged.
Only realtime and simulated connections can match (422 matching_requires_realtime). The first match on a connection starts building its index, and until it’s in every match is refused with 409 name_index_building. To have it ready ahead of time, and be told when it is, opt in with POST /connections/{connection_id}/name-index and a webhook_url. Every match counts as a use: an index is kept current while it was used in the last 7 days, and deleted after 30 days unused.
Send the names in the JSON body: a match in the query string is refused, since URLs end up in logs. QuBe Sync doesn’t log them either. A match changes nothing, so it takes no Idempotency-Key.
curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/matches \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"fields": {
"email": "[email protected]"
},
"kind": "customer",
"name": "ACME, Inc."
}
'{
"candidates": [
{
"full_name": "Acme Inc",
"is_active": true,
"list": "customer",
"list_id": "80000011-1712345678",
"reasons": [
"same after removing punctuation and suffixes"
],
"score": 1
},
{
"full_name": "Acme LLC",
"is_active": false,
"list": "customer",
"list_id": "80000012-1712345678",
"reasons": [
"same after removing punctuation and suffixes"
],
"score": 1
}
],
"candidates_total": 2,
"candidates_total_complete": true,
"index": {
"as_of": "2026-10-11T14:02:10Z",
"state": "ready"
},
"match": "candidates",
"record": null
}Authorizations
Use your app's API key as the username, and leave the password blank
Path Parameters
The connection to act on.
Body
Which lists to look in. entity is customers, vendors, employees and other names together, which share one name space in QuickBooks; item is every item type. Any other kind is its own list.
customer, vendor, employee, other_name, entity, item, account, class, standard_terms, date_driven_terms, sales_tax_code, payment_method, ship_method, price_level, customer_type, vendor_type, job_type, sales_rep, customer_msg The name your app has for the record: its own name, without its parent's when you send parent. Without a parent, a full name such as Smith:Kitchen is matched exactly too. Its words with a digit (a store, unit or job number, such as 1234 in Subway #1234) must agree with a record's, leading zeros aside.
1 - 255"ACME, Inc."
true answers only exact or none: the one record with this full name, as QuickBooks compares names, or nothing. Never a fuzzy match, so its answer can be used without asking. fields are ignored.
For customers, vendors, employees and other names (customer, vendor, employee, other_name and entity): what else your app knows about the record. The same account_number makes a strong match whatever the name. The same email, phone or postal_code, with a name at least 0.4 alike, makes a strong match. Each one in common is a reason and ranks a candidate higher; company_name and city do only that. An email's or account number's case doesn't count, nor a phone's punctuation, country code or extension, nor a postal code's spaces or a US ZIP+4's last four digits. The city and postal_code are compared with the record's billing address (a vendor's, employee's or other name's own address).
Show child attributes
Show child attributes
This call's candidate threshold, in place of 0.44: raise it to list only close names, lower it (down to 0.3, the least alike a match reads) to list more. A record that's a candidate for another reason (two letters swapped, or strong but not alone) stays one, and exact and strong don't change. Not taken with exact_only: true.
0.3 <= x <= 1For a job, a sub-item, a subaccount or the like: its parent's full name or ListID, so only that parent's children are matched. Without one, children match on their own name too, with a reason naming the parent. Taken for customer, entity, item, account, class, customer_type, vendor_type and job_type. A parent the index doesn't hold matches nothing.
255"Smith"
Response
The answer, from the index as it stands.
A match's answer: the tier, and the record or the candidates.
For candidates: up to 10 records, best first (exact or strong ones that weren't alone, those with your account_number first; then those with the same numbers in their name, then those with your numbers and more; then the most fields in common; then the highest score), for a person to choose from. Empty otherwise. candidates_total says how many qualified.
10Show child attributes
Show child attributes
For candidates: how many records qualified, of which candidates lists the first 10; 0 for any other tier. More than 10 means the name alone doesn't pick out a record, as in a file of numbered locations (Subway #1201, Subway #1202...). Rather than show a long list of near-identical names, ask for what tells them apart (the number, a city, a postal code, an account number) and match again with it.
x >= 0false when candidates_total is a lower bound: a match reads at most 50 records, the most alike first, and it read that many, so more may qualify. true otherwise, and always for exact, strong and none.
The index the answer came from.
Show child attributes
Show child attributes
The first tier that applies. exact: one record has this full name, as QuickBooks compares names (case and the spaces at either end don't count, and a run of spaces matches one). strong: exactly one record is the same once punctuation, accents, &, a leading the, company suffixes (Inc, LLC, Co...), spacing or word order are set aside; or has the same number in its name and a name at least 0.4 alike (Subway #1234 for Subway Store 1234); or (customers, vendors, employees and other names) has the account_number you sent, or shares the email, phone or postal_code you sent and has a name at least 0.4 alike. Two or more like that are candidates instead. candidates: records whose names are like this one, best first. none: nothing like it. A name's numbers must agree: when both names have words with a digit (leading zeros aside), the record must have every one you sent. One with a different number instead is neither strong nor a candidate, unless it's exact or has the account_number you sent. One with your numbers and more (7-Eleven #42 for 7-Eleven) can be a candidate, never strong. With exact_only, only exact or none.
exact, strong, candidates, none The record, for exact and strong; null otherwise. Use an exact match as it is. Confirm a strong one first, as you would a candidate: Acme Inc and Acme LLC are a strong match, and can be two companies.
Show child attributes
Show child attributes