> ## Documentation Index > Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/v2/openapi.json post /connections/{connection_id}/matches openapi: 3.1.0 info: contact: email: support@qubesync.com description: > A single generic operation surface for every curated qbXML request QuBe Sync supports, driven directly off the qbXML schema -- see the [MCP server](/mcp-server) to explore available operations interactively. **Every endpoint queues a request and returns it immediately (`201`, a `QueuedRequest`).** QuickBooks Desktop is reached through the customer's Web Connector, which polls QuBe Sync, so the answer arrives seconds to minutes later. **Pass a `webhook_url` with every request**: when QuickBooks has answered, QuBe Sync POSTs the same document to it -- `state` set, `response_json` filled in -- signed with `X-QUBE-Signature` (see the Webhooks guide). `response_json` is the `{status, data}` envelope documented on each operation: `status: "success"` with `data` derived from the qbXML `*Ret` (and `warning`, QuickBooks' code and message, when it carried the request out but warned about it), or `status: "error"` with QuickBooks' own status code and message -- a QuickBooks business error is a *successful* HTTP round trip. `links.self` returns the request on demand (for a dashboard, a retry, a script); it is not the integration path. Send an `Idempotency-Key` header with each request so a call whose answer you never got can be sent again without queueing it twice. Authentication is HTTP Basic with your app's API key as the username and a blank password. Connections themselves (creating one, onboarding, its QWC file and password) are the `/connections` endpoints; every QuickBooks operation is scoped to one of them. title: QuBe Sync API (v2) version: 2.0.0 servers: - description: v2 API url: https://qubesync.com/api/v2 - description: Local development server url: https://dev.qubesync.com/api/v2 security: - apiKey: [] tags: - description: >- Creating and managing the connection (a customer's QuickBooks company file) that every request below is queued against. See the Onboarding guide. name: Connections - description: >- Queueing qbXML you wrote yourself, listing the requests queued on a connection, and discarding one the app no longer wants. A `webhook_url` on each request is the integration path (see the Webhooks guide): the listing is for a dashboard, a script, or catching up after downtime. name: Queued Requests - description: >- Finding the record in a customer's company file that a name means, even written differently: ranked matches from QuBe Sync's index of the file's names, on realtime and simulated connections. See the Matching guide. name: Matching - description: >- Endpoints for publishing workflow definitions, starting runs, and answering a run that is waiting on a decision from your app. A workflow is one JSON statechart document; see the schema at /api/v2/workflows/schema.json. name: Workflows - name: Account Tax Line Infos - name: Accounts - name: Aging Reports - name: Alerts - name: Ar Refund Credit Cards - name: Bar Codes - name: Bill Payment Checks - name: Bill Payment Credit Cards - name: Bill To Pays - name: Billing Rates - name: Bills - name: Budget Summary Reports - name: Build Assemblies - name: Charges - name: Checks - name: Classes - name: Cleared Statuses - name: Companies - name: Company Activities - name: Credit Card Charges - name: Credit Card Credits - name: Credit Memos - name: Currencies - name: Custom Detail Reports - name: Custom Summary Reports - name: Customer Msgs - name: Customer Types - name: Customers - name: Data Event Recovery Infos - name: Data Ext Defs - name: Data Exts - name: Date Driven Terms - name: Deposits - name: Employee Defaults - name: Employees - name: Entities - name: Estimates - name: Form1099 Category Account Mappings - name: General Detail Reports - name: General Summary Reports - name: Hosts - name: Inventory Adjustments - name: Inventory Sites - name: Invoices - name: Item Assemblies Can Builds - name: Item Discounts - name: Item Fixed Assets - name: Item Groups - name: Item Inventories - name: Item Inventory Assemblies - name: Item Non Inventories - name: Item Other Charges - name: Item Payments - name: Item Receipts - name: Item Sales Tax Groups - name: Item Sales Taxes - name: Item Services - name: Item Sites - name: Item Subtotals - name: Items - name: Job Reports - name: Job Types - name: Journal Entries - name: Leads - name: List Deleteds - name: List Displays - name: List Merge - name: Lists - name: Other Names - name: Paychecks - name: Payment Methods - name: Payments - name: Payroll Detail Reports - name: Payroll Item Additions - name: Payroll Item Company Contributions - name: Payroll Item Deductions - name: Payroll Item Direct Deposits - name: Payroll Item Non Wages - name: Payroll Item Taxes - name: Payroll Item Wages - name: Payroll Item Workers Compensations - name: Payroll Items - name: Payroll Last Periods - name: Payroll Liability Adjustments - name: Payroll Liability Checks - name: Payroll Prior Payments - name: Payroll Summary Reports - name: Payroll Year To Date Adjustments - name: Preferences - name: Price Levels - name: Purchase Orders - name: Qb Command Exec - name: Receive Payment To Deposits - name: Receive Payments - name: Sales Orders - name: Sales Receipts - name: Sales Reps - name: Sales Tax Codes - name: Sales Tax Payables - name: Sales Tax Payment Checks - name: Sales Tax Return Lines - name: Sales Tax Returns - name: Ship Methods - name: Special Accounts - name: Special Items - name: Standard Terms - name: Templates - name: Terms - name: Time Reports - name: Time Trackings - name: To Dos - name: Transactions - name: Transfer Inventories - name: Transfers - name: Txn Deleteds - name: Txn Displays - name: Txn Void - name: Txns - name: Unit Of Measure Sets - name: Vehicle Mileages - name: Vehicles - name: Vendor Credits - name: Vendor Types - name: Vendors - name: Workers Comp Codes paths: /connections/{connection_id}/matches: post: tags: - Matching summary: Match a name description: >- 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`. operationId: matchRecords parameters: - description: The connection to act on. in: path name: connection_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: a_customer: summary: A customer, with its email value: fields: email: ap@acme.example kind: customer name: ACME, Inc. a_job: summary: A job under a customer value: kind: customer name: Kitchen parent: Smith a_store: summary: A numbered location, with its city value: fields: city: Austin kind: customer name: Subway Store 1234 any_name: summary: Any customer, vendor, employee or other name value: kind: entity name: Riverbend Electric by_account_number: summary: By your own id, kept in the account number value: fields: account_number: crm-1001 kind: customer name: ACME, Inc. exact_only: summary: Only an exact match value: exact_only: true kind: item name: Consulting schema: additionalProperties: false properties: exact_only: default: false description: >- `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. nullable: true type: boolean fields: additionalProperties: false description: >- 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). nullable: true properties: account_number: description: >- The record's account number in QuickBooks. An app that creates the records can set it to its own id, and match on it later, if the company doesn't use the field for something else. maxLength: 255 nullable: true type: string city: maxLength: 255 nullable: true type: string company_name: description: >- Compared once punctuation and suffixes are set aside. Not for `employee`: QuickBooks employees have no company name. maxLength: 255 nullable: true type: string email: maxLength: 1023 nullable: true type: string phone: maxLength: 50 nullable: true type: string postal_code: maxLength: 50 nullable: true type: string type: object kind: description: >- 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. enum: - 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 type: string min_score: description: >- 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`. maximum: 1 minimum: 0.3 nullable: true type: number name: description: >- 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. example: ACME, Inc. maxLength: 255 minLength: 1 type: string parent: description: >- For 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. example: Smith maxLength: 255 nullable: true type: string required: - kind - name type: object required: true responses: '200': content: application/json: examples: candidates: summary: Candidates value: 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 exact: summary: An exact match value: candidates: [] candidates_total: 0 candidates_total_complete: true index: as_of: '2026-10-11T14:02:10Z' state: ready match: exact record: full_name: Smith:Kitchen is_active: true list: customer list_id: 80000027-1712345678 reasons: - same name score: 1 strong: summary: A strong match, by its number value: candidates: [] candidates_total: 0 candidates_total_complete: true index: as_of: '2026-10-11T14:02:10Z' state: ready match: strong record: full_name: 'Subway #1234' is_active: true list: customer list_id: 80000042-1712345678 reasons: - similar name - same number score: 0.71 schema: $ref: '#/components/schemas/Match' description: The answer, from the index as it stands. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': content: application/json: example: errors: code: name_index_building detail: >- This call started building the connection's name index: QuBe Sync is reading the names in its lists from QuickBooks, a step at a time, the next times the Web Connector checks in. Matching answers once it's in. To be told when it is, POST /api/v2/connections/3f9c2a71-5d4e-4b8a-9c1f-7e2d6a5b8c90/name-index with a webhook_url: QuBe Sync sends name_index.ready there when the build finishes (or name_index.failed if it gives up). Or read the connection's name_index.state until it is ready. schema: $ref: '#/components/schemas/Error' description: >- `name_index_building`: the connection's name index isn't in yet. The first match, or opt-in, starts it; it takes a few Web Connector sessions. `detail` says whether this call started it, and how to be told when it's ready. '422': content: application/json: examples: invalid: summary: A body it can't take value: errors: name: - can't be blank matching_requires_realtime: summary: A standard connection value: errors: code: matching_requires_realtime detail: >- Matching needs a realtime or simulated connection, and this one is standard. Upgrade it to realtime from its page in the dashboard; in a sandbox app that costs nothing, since sandbox apps aren't billed. A simulated connection matches against the simulator's company file. schema: $ref: '#/components/schemas/Error' description: >- `matching_requires_realtime`: the connection is `standard`, which has no name index. Or the body was refused field by field: a `kind` that isn't one of the list, a blank `name`, a value that's too long, `fields` for a kind that isn't a customer, vendor, employee or other name, a field the kind's records don't have (`company_name` for an employee), a `parent` for a kind whose records have none, an `exact_only` that isn't `true` or `false`, a `min_score` outside 0.3 to 1.0 or sent with `exact_only: true`, a parameter it doesn't take, or the match sent in the query string. security: - apiKey: [] components: schemas: Match: description: 'A match''s answer: the tier, and the record or the candidates.' properties: candidates: description: >- 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. items: $ref: '#/components/schemas/MatchRecord' maxItems: 10 type: array candidates_total: description: >- 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. minimum: 0 type: integer candidates_total_complete: description: >- `false` 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`. type: boolean index: description: The index the answer came from. properties: as_of: description: >- When the index last caught up with QuickBooks: a record added, renamed or deleted in QuickBooks since then isn't reflected yet. format: date-time type: string state: enum: - ready type: string required: - state - as_of type: object match: description: >- 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`. enum: - exact - strong - candidates - none type: string record: anyOf: - $ref: '#/components/schemas/MatchRecord' - type: 'null' description: >- 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. required: - match - record - candidates - candidates_total - candidates_total_complete - index type: object Error: description: >- What a refused request answers with. The one key is errors, and its shape says what went wrong: a sentence when the endpoint explains the refusal in words (a parameter the operation does not take, a key already taken, a run that has already ended); an object with detail, and a code when there is one, when the request named nothing that exists or may not do what it asked (402, 403, 404, and a CLI session's 401), or an answer to a run's question was refused (the decisions endpoint's 400, 409 and 422, which always carry a code to branch on); an object of fields, each a list of messages, when a record failed validation and nothing was saved; a list of {path, message} problems when a submitted document or input fails validation. A request without a usable API key gets a 401 Basic challenge with the plain-text body Unauthorized, not JSON. properties: errors: oneOf: - example: 'unknown parameter: "emial"' title: A sentence type: string - properties: code: example: read_only_session type: string detail: example: Not Found type: string required: - detail title: Detail and code type: object - additionalProperties: items: type: string type: array example: webhook_url: - may not contain a username or password title: Field by field type: object - items: properties: message: example: is required type: string path: example: input.customer type: string required: - path - message type: object title: Located problems type: array required: - errors type: object MatchRecord: description: >- A record a match found: enough to show it, and its `list_id` to use it by. The index can be a few minutes behind QuickBooks (`index.as_of`), so read the record by its `list_id` before a change depends on it: one renamed since comes back with its new name, and one deleted since is a 3120 (or an empty answer). properties: email: description: >- Its email, as the index holds it (lower-cased), for a person to tell candidates apart; null when it has none or isn't a customer, vendor, employee or other name. example: ap@acme.example nullable: true type: string full_name: description: >- Its full name: a job's or a sub-item's starts with its parent's, `Smith:Kitchen`. example: Acme Inc type: string is_active: description: >- `false` for an inactive record. QuickBooks hides those from most lists, but they keep their names: adding another with the same name is a 3100. type: boolean list: description: >- The list it's in: `customer`, `vendor`, `employee` or `other_name`, an item type such as `item_service`, or the list you matched in, such as `account`. example: customer type: string list_id: description: >- The record's ListID: what a reference (`customer_ref`, `item_ref`...) names it by. example: 80000011-1712345678 type: string phone: description: >- Its phone, for a person to tell candidates apart: a 10-digit one as `512-555-0142`, else as QuickBooks has it; null when it has none. example: 512-555-0142 nullable: true type: string reasons: description: >- Why it matched, as phrases you can show: first how the name compares (`same name`, `same after removing punctuation and suffixes`, `same words in a different order`, `same apart from spacing`, `two letters swapped`, `similar name`, or `different name` for a record found by its account number alone), then `same number` when the numbers in the names agree (or `the number asked, and more` when the record's name has every number sent and others too), then what else is the same (`same account number`, `same email`, `same phone`, `same postal code`, `same city`, `same company name`), and, for a job or sub-item matched without a `parent`, whose it is (`a job under Smith`). example: - same after removing punctuation and suffixes items: type: string type: array score: description: >- How alike the names are, from 0 to 1: the trigram similarity of the two names once case, accents, punctuation and company suffixes are set aside. `1.0` for an exact match. A candidate has at least 0.44 (or the `min_score` you sent), unless it's there for another reason. example: 0.86 maximum: 1 minimum: 0 type: number required: - list_id - full_name - list - is_active - score - reasons - email - phone type: object responses: Unauthorized: content: text/plain: example: Unauthorized schema: type: string description: >- No usable API key. The key is Basic auth, so the answer is the challenge, with the plain-text body Unauthorized rather than JSON. headers: WWW-Authenticate: schema: example: Basic realm="Application" type: string NotFound: content: application/json: example: errors: detail: Not Found schema: $ref: '#/components/schemas/Error' description: Nothing by that id, or it belongs to another app. securitySchemes: apiKey: description: Use your app's API key as the username, and leave the password blank scheme: basic type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.