> ## 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. # Search for the record a question's field means > For a `record` field of the question the run is asking (a field of type `record` in one of `prompt.choices`): the records of its `kind` whose names are like `q`, from the connection's name index -- what a person types into a search box, one call per pause in their typing. GET the run's `links.search`, which carries the prompt's `token`, adding `field` and `q`; answer the choice with the `value` of the one picked as that field. At most 20, ranked as matching ranks them: the exact name first, then names that start with `q`, then the most alike. Only a realtime or simulated connection has a name index, so only there does a prompt carry a search choice and `links.search`. While the index is being built, the search is refused with `409 name_index_building`, as a match is. `q` is a name your user typed: keep it out of your own logs as QuBe Sync keeps it out of its own. ## OpenAPI ````yaml /api-reference/v2/openapi.json get /connections/{connection_id}/workflow-runs/{run_id}/search 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}/workflow-runs/{run_id}/search: get: tags: - Workflows summary: Search for the record a question's field means description: >- For a `record` field of the question the run is asking (a field of type `record` in one of `prompt.choices`): the records of its `kind` whose names are like `q`, from the connection's name index -- what a person types into a search box, one call per pause in their typing. GET the run's `links.search`, which carries the prompt's `token`, adding `field` and `q`; answer the choice with the `value` of the one picked as that field. At most 20, ranked as matching ranks them: the exact name first, then names that start with `q`, then the most alike. Only a realtime or simulated connection has a name index, so only there does a prompt carry a search choice and `links.search`. While the index is being built, the search is refused with `409 name_index_building`, as a match is. `q` is a name your user typed: keep it out of your own logs as QuBe Sync keeps it out of its own. parameters: - description: ID of the connection in: path name: connection_id required: true schema: format: uuid type: string - description: ID of the workflow run in: path name: run_id required: true schema: format: uuid type: string - description: >- The `name` of a `record` field of one of the prompt's choices, or a `rows` field's record column as `.` (`records.list_id`). example: list_id in: query name: field required: true schema: type: string - description: >- For a `rows` field's record column: the row's `key`, whose `kinds` says the list searched. Needed when the column's `kind` is null. example: customer_ref in: query name: row required: false schema: type: string - description: 'What the person typed: 2 to 100 characters, once trimmed.' example: Lone in: query name: q required: true schema: maxLength: 100 minLength: 2 type: string - description: >- The `token` of the prompt being answered, as `links.search` carries it. Refused with `409 prompt_changed` once the run has asked again or moved on. in: query name: prompt_token required: false schema: type: string responses: '200': content: application/json: example: data: - detail: >- Customer · ar@lonestar.example · 512-555-0142 · Austin 78701 label: Lone Star Supply value: 80000012-1712345678 - detail: Vendor · inactive label: Lone Star Supply Co value: 80000031-1712399999 schema: properties: data: items: properties: detail: description: >- Its list, `inactive` when it is, then what tells it apart, as far as the index holds it: company name, email, phone, city and postal code, account number. Parts joined with ` · `, for a person to read. example: >- Customer · ar@lonestar.example · 512-555-0142 · Austin 78701 type: string label: description: The record's full name. example: Lone Star Supply type: string value: description: 'What to answer the field with: the record''s ListID.' example: 80000012-1712345678 type: string required: - value - label - detail type: object maxItems: 20 type: array required: - data type: object description: >- The records like `q`, best first: at most 20, and none when nothing is. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- No run with that id on that connection, or the connection does not belong to this app. '409': content: application/json: example: errors: code: prompt_changed detail: >- the run isn't asking this question any more; search from its prompt as it is now schema: $ref: '#/components/schemas/Error' description: >- `prompt_changed` (`errors.code`): the run isn't asking the question `prompt_token` names any more -- it has asked again, or moved on. Read the run for the question it is asking now. Or `name_index_building`: the connection's name index is still being built (`errors.detail` says how to be told when it is ready); search again then. '422': content: application/json: example: errors: code: invalid_q detail: q must be 2 to 100 characters schema: $ref: '#/components/schemas/Error' description: >- The search is refused: `invalid_field` (`field` isn't a `record` field of the prompt's choices, or a `rows` field's record column; `errors.detail` names the ones it has), `invalid_row` (a column whose list depends on the row, searched without one of its rows' `key`), `invalid_q` (`q` is missing, or not 2 to 100 characters), `invalid_prompt_token` (`prompt_token` was not a string), or `matching_requires_realtime` (the connection has no name index any more: it was made standard). security: - apiKey: [] components: schemas: 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 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.