> ## 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 template, before it's installed > The template's usage contract: how to start it, every question it may ask (including those of the templates it calls), and every way it can end. The same shape `GET /workflows/{key}/usage` answers for an installed workflow, built from the template's chart and the charts of the templates it calls, as if `POST /workflow-templates/{key}/install` had installed them together, so you can read what it asks and how it ends before installing anything. `workflow.state` is `template`. It reads nothing of your app: once you've installed or adapted it, `GET /workflows/{key}/usage` describes the workflow your app actually runs. ## OpenAPI ````yaml /api-reference/v2/openapi.json get /workflow-templates/{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: /workflow-templates/{key}/usage: get: tags: - Workflows summary: How to use a workflow template, before it's installed description: >- The template's usage contract: how to start it, every question it may ask (including those of the templates it calls), and every way it can end. The same shape `GET /workflows/{key}/usage` answers for an installed workflow, built from the template's chart and the charts of the templates it calls, as if `POST /workflow-templates/{key}/install` had installed them together, so you can read what it asks and how it ends before installing anything. `workflow.state` is `template`. It reads nothing of your app: once you've installed or adapted it, `GET /workflows/{key}/usage` describes the workflow your app actually runs. parameters: - description: The template's key (see GET /workflow-templates) in: path name: key required: true schema: pattern: ^[a-z][a-z0-9_]{0,63}$ 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 template 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.