Match records
match_recordsFinds the record in a customer's QuickBooks company file that a name means, even written differently -- QuickBooks itself only matches a name exactly, or by 'contains' on one list. Checks the arguments and returns the v2 request to send (POST /api/v2/connections/{connection_id}/matches); it never touches a connection. Matching needs a realtime or simulated connection: a standard one answers 422 matching_requires_realtime (switching a sandbox connection to realtime is free). The first match on a connection starts building its name index and answers 409 name_index_building until it's ready, a few Web Connector sessions later; POST /api/v2/connections/{connection_id}/name-index with a webhook_url to start it ahead and be sent name_index.ready. The answer's match is a tier: exact (the full name, as QuickBooks compares names: use record), strong (exactly one record is the same once punctuation, accents, company suffixes such as Inc/LLC, spacing or word order are set aside, has the same number in its name (Subway #1234 for Subway Store 1234), has the account number sent, or shares the email, phone or postal code: likely, so confirm record before using it), candidates (up to 10 ranked records with a score and reasons: ask which, if any) or none. Numbers in names must agree: Subway #1235 is never offered for Subway #1234. When candidates_total is more than a person can choose from (a file of numbered locations), ask for what tells them apart -- the number, city, postal_code or account_number -- and match again with it. exact_only: true answers exact or none; min_score moves the candidate threshold for one call. Match a record once: when it's confirmed, store its list_id and refer to it by that (customer_ref: {list_id}); match again only when a stored list_id stops working.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"kind": "<kind>",
"name": "<name>"
},
"name": "match_records"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Which lists to look in. entity is customers, vendors, employees and other names together (one name space in QuickBooks); item is every item type. | |
| name | Yes | The name the app has for the record: its own name, without its parent's when parent is given. | |
| fields | No | For customer, vendor, employee, other_name, entity only: what else the app knows. 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. company_name and city only rank a candidate higher. city and postal_code are the record's billing (or main) address's. company_name isn't taken for employee. | |
| parent | No | For a job, sub-item, subaccount and the like: the parent's full name or ListID, so only its children match. Taken for customer, entity, item, account, class, customer_type, vendor_type, job_type. | |
| min_score | No | This call's candidate threshold, in place of 0.44: raise it to list only close names, lower it to list more. Not with exact_only. | |
| exact_only | No | true answers only exact or none, never a fuzzy match, so the answer can be used without asking. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| body | Yes | ||
| answer | Yes | The JSON Schema of the 200 answer. | |
| method | Yes |