> ## 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. # How to use a workflow > Everything needed to call this workflow: how to start it, every question it may ask (including from workflows it calls), and every way it can end. Derived from the chart on every request, so it always describes the workflow that actually runs. ## OpenAPI ````yaml /api-reference/v2/openapi.json get /workflows/{key}/usage 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: /workflows/{key}/usage: get: tags: - Workflows summary: How to use a workflow description: >- Everything needed to call this workflow: how to start it, every question it may ask (including from workflows it calls), and every way it can end. Derived from the chart on every request, so it always describes the workflow that actually runs. parameters: - description: The workflow's stable key in: path name: key required: true schema: pattern: ^[a-z][a-z0-9_]{0,63}$ type: string - description: >- Which chart to describe: a version number, `published` (the default), or `working` for the working copy. in: query name: version required: false schema: type: string responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/WorkflowUsage' type: object description: The usage contract '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: No workflow with that key security: - apiKey: [] components: schemas: WorkflowUsage: description: Derived from the chart; nothing here is stored or hand-written. properties: child_outcomes: description: >- Per `workflow` state, every outcome the workflow it calls declares. A called workflow's ending arrives as an ordinary `success` (a declared failure as `error`) with `response.outcome` naming it, so a state that does not branch on it carries on as though nothing unusual happened. Each has `state`, `workflow`, `outcome`, `kind` (`success` or `failure`), `description`, `handled_at` (the state, or the state enclosing it, that branches on this outcome; `root on.success` or `root on.error` when the chart's root does; null when nothing does) and `per_item` (true when the state runs once per item, so each element's ending arrives in `response.outcomes` instead). Empty when the workflow calls none, or none that is installed. items: type: object type: array decision_flow: description: >- How answering a question works, whatever the question: `asynchronous` (a run waits for an answer indefinitely); `delivery`, the `workflow_run.awaiting_input` webhook a question arrives in (`event`, where it is sent, `signature_header`, `answer_url`, the `payload` envelope, and `order`: how to match a webhook to your record by `reference` and put the run's bodies in order by `revision`); `answer`, the request that answers it (`method`, `path`, `auth`, a `body` template, `data_note`, `token_note` (why the body names the prompt's `token`) and `response`, plus, when the workflow asks anything, a `response_example` of answering its first question and an `error_example` of the 422 a wrong option gets); `poll`, reading the run instead of waiting for the webhook; `cancel`, stopping the run instead (its request, a `note` and its `errors`); `composed`, how a question asked by a workflow this one calls arrives (`applies` is true when this workflow has one); and `errors`, what the decisions endpoint can refuse an answer with (`status`, `code` and `meaning` each). type: object decisions: description: >- Every question the workflow may ask, including ones asked by workflows it calls (their ids are prefixed by the calling state). Each carries its `kind` (`decision` for a wait state's question, `conflict` for the prompt the engine asks when an update whose `on_conflict` is `ask` meets a stale edit sequence; those come after the wait states' and have id `conflict:`), the message as authored (for a conflict, `when` says when it is asked), the options and their fields, a `webhook_example` of the payload it arrives in, one `answers` body per option, and `data`: per `prompt.data` key, where it comes from and an `example` of what it carries -- the record from the request that fills it when exactly one does, and a placeholder otherwise; for a conflict, a `description` of each key. items: type: object type: array matches: description: >- Every match state the workflow can look a record up by name from, including those of workflows it calls (their `state` is prefixed by the calling state): `state`, `leaf_state` and `workflow` (where it is), `in_child`, `kind` (the list it looks in, as the chart writes it: a kind such as `customer`, or a template), `description`, `refresh` (whether it refreshes the connection's name index from QuickBooks first: `true`, `false`, or the template that says), `exact_only` and `error_handled` (whether the workflow handles a match it can't ask; otherwise the run fails). Each raises `success` whatever it finds, with `response.data` the answer the matches endpoint gives -- `match` (`exact`, `strong`, `candidates` or `none`), `record`, `candidates`, `candidates_total`, `candidates_total_complete` and `index` -- with `index.state` `unavailable` (and no scores) when a standard connection answered from QuickBooks' own filters. No QuickBooks status codes. Empty when it matches nothing. items: type: object type: array notifications: description: >- Every notify state the workflow can send the app data from, including those of workflows it calls (their `state` is prefixed by the calling state): `name` (what the app routes on), `description`, `state` (the webhook's `state`, its path from the run), `leaf_state` and `workflow` (where it is, in the workflow that sends it), `sent_by_child`, `per_item_of` (the calling state that runs once per item, when it is sent from inside one; null otherwise), `error_handled` (whether the workflow handles it not being delivered; otherwise the run fails), `data_example` (what `data` carries, from the chart: a record's identifying fields where it sends a request's response, placeholders for what only exists mid-run) and `webhook_example`, the whole `workflow_run.notification` it arrives in. A run of a workflow with any must be started with a `webhook_url`. Empty when it sends none. items: type: object type: array outcomes: description: >- One entry per ending the run can reach: the successes, then the failures the workflow declares, then `failed`. Each has `outcome`, `kind` (`success` or `failure`), `description` and `from_states`, the states that lead there. A success carries `output_keys` and an `output_example`, and so does a declared failure with an output of its own: per key, its `values` when they are known (a key that is `${meta.outcome}` has the ending's own name), else `source`, the states whose responses feed it, with that operation's `shape` when there is one; `may_be_null` flags a key that may not be set. `completed` is listed only when something in the chart reaches it, or when the workflow declares no success of its own. A declared failure lists the `errors` it can carry; `failed` is always listed, with the messages this workflow can end with (`authored_errors`), the ones that carry a QuickBooks message or a called workflow's error through (`dynamic_errors`), and the engine's own (`engine_errors`). items: type: object type: array per_item: description: >- One entry per `workflow` state that runs once per element of a list: `state` (its path), `workflow` (the key it calls), `each` (the list, as the chart writes it), `as` (the name each element is bound to; `item` unless the state names another), `on_item_error` (`stop` or `continue`), `stop_on` (the called workflow's endings that end the loop at the element that ends in one, starting none after it; `[]` for none), and `sentence`, the same said in one sentence. Empty when nothing in the workflow runs once per item. items: type: object type: array request_errors: description: >- Per request state, the QuickBooks status codes its operation can raise and whether this workflow handles each one; `settle`, whether a request QuickBooks never answered is settled before the state raises anything; and `on_conflict`, for an update, what happens when the record changed after it was read (`ask`, `overwrite` or `fail`; null for anything that is not an update). A request state whose `operation` is a template (`${input..operation}`) is listed with `operation` null, `operation_template` the template and no codes, since the operation is decided when the run starts. items: type: object type: array run_json_example: type: object start: description: >- The request that starts a run: method, path, an example body, the input JSON Schema, and a note per declared input. type: object states: description: What each run state means, in lifecycle order. items: type: object type: array webhooks: description: >- The webhooks a run of this workflow sends, each with `event` and `when`: `workflow_run.awaiting_input`, `workflow_run.notification` when it has notify states, and the three endings. items: type: object type: array workflow: description: >- key, name, description and state: `draft` or `published` for a workflow, `template` for a shipped template read before it's installed. type: object 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 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.