curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"workflow": "<string>",
"input": {},
"reference": "order-1042",
"version": "<string>",
"webhook_url": "<string>"
}
'import requests
url = "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs"
payload = {
"workflow": "<string>",
"input": {},
"reference": "order-1042",
"version": "<string>",
"webhook_url": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
workflow: '<string>',
input: {},
reference: 'order-1042',
version: '<string>',
webhook_url: '<string>'
})
};
fetch('https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'workflow' => '<string>',
'input' => [
],
'reference' => 'order-1042',
'version' => '<string>',
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs"
payload := strings.NewReader("{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"cancel_reason": "<string>",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"current_state": "create_customer / resolve_conflict.find_holder",
"error": {
"code": 3100,
"hint": "<string>",
"message": "<string>",
"quickbooks_message": "<string>",
"type": "name_in_use"
},
"headline": "Created Riverbend Electric in QuickBooks.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"input": {},
"links": {
"cancel": "<string>",
"decisions": "<string>",
"search": "<string>",
"self": "<string>",
"ui": "<string>"
},
"outcome": "<string>",
"output": {},
"prompt": {
"choices": [
{
"description": "Try the add again under a name you choose.",
"detail": "Customer · similar name",
"fields": [
{
"label": "New name",
"name": "name",
"required": true,
"type": "string",
"columns": [
{
"enum": [
{
"label": "Service",
"value": "item_service"
}
],
"kind": "account",
"label": "Income account",
"name": "income_account",
"required": true,
"type": "string",
"when": {
"action": [
"create"
]
}
}
],
"enum": [
{
"label": "Service",
"value": "item_service"
}
],
"kind": "customer",
"rows": [
{
"columns": [
"action",
"list_id",
"income_account"
],
"detail": "Item",
"key": "invoice_line_add.0.item_ref",
"kinds": {
"income_account": "account",
"list_id": "item"
},
"label": "Vinyl Banner",
"values": {
"item_type": "item_non_inventory"
}
}
]
}
],
"id": "rename",
"label": "Add it under another name"
}
],
"details": [
{
"label": "Customer",
"value": "Lone Star Supply Co"
}
],
"kind": "decision",
"token": "<string>"
},
"reference": "<string>",
"revision": 2,
"state": "running",
"summary": {
"calls": [
{
"item_index": 123,
"outcome": "<string>",
"state": "create_customer",
"status": "completed",
"workflow": "<string>"
}
],
"changes": [
{
"action": "create",
"kind": "customer",
"full_name": "<string>",
"item": 123,
"list_id": "<string>",
"ref_number": "<string>",
"settled": "found",
"txn_id": "<string>"
}
],
"decisions": [
{
"at": "2023-11-07T05:31:56Z",
"item_index": 123,
"option": "<string>",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"discarded": [
{
"item_index": 123,
"items_not_started": 123,
"message": "<string>",
"operation": "<string>",
"queued_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"ended_at": "2023-11-07T05:31:56Z",
"matches": [
{
"candidates": 123,
"candidates_total": 123,
"candidates_total_complete": true,
"index": "ready",
"item_index": 123,
"match": "exact",
"state": "<string>",
"workflow": "<string>"
}
],
"notifications": {
"failed": 123,
"sent": 123
},
"requests": [
{
"evidence": "of 2 candidates with reference number \"1044\", one carries the GUID sent (txn_id 2-1), so the add was applied",
"found_by": "look_for_invoice",
"identifiers": {
"full_name": "<string>",
"list_id": "<string>",
"ref_number": "<string>",
"txn_id": "<string>"
},
"item_index": 123,
"operation": "<string>",
"pages": 123,
"role": "prepare",
"settled": "found",
"state": "create_customer / try_create",
"status": "success",
"unconfirmed": true,
"workflow": "<string>"
}
],
"side_effects": [
{
"evidence": "<string>",
"identifiers": {
"full_name": "<string>",
"list_id": "<string>",
"ref_number": "<string>",
"txn_id": "<string>"
},
"item_index": 123,
"operation": "<string>",
"settled": "found",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"stopped_at": "create_customer / resolve_conflict.ask_about_customer",
"unconfirmed": [
{
"item_index": 123,
"operation": "<string>",
"state": "add_invoice",
"workflow": "<string>"
}
]
},
"trace": [
{
"at": "2023-11-07T05:31:56Z",
"event": "<string>",
"from": "<string>",
"to": "<string>"
}
],
"vars": {},
"workflow": "<string>"
}
}Start a workflow run
input is validated against the workflow’s declared inputs before anything is queued, so a bad request body comes back as a 422 with paths rather than failing inside QuickBooks later. A draft workflow may only be run against a sandbox connection. The run is returned in the state it has reached: one that ends as it starts (a chart that fails before sending anything, or needs no QuickBooks request) is already failed or completed, and its workflow_run.* webhook can reach you before this response does. Send a reference — your own label for this run, such as the id of the record it is about, and a new one for every run — and save your record before you send this call: every webhook carries the reference, so one that arrives before this response still finds its record. Send an Idempotency-Key: if this response never reaches you, sending the call again with the same key answers with that run instead of starting another.
Workflows run on realtime connections, and on simulated ones. On a standard connection this is a 422 realtime_required with nothing stored, the Idempotency-Key included, so once the connection is upgraded to realtime (from its page in the dashboard: a connection’s type can’t be changed through the API) the same call starts the run. A realtime connection slowed to the standard pace, or with a downgrade scheduled, still runs workflows; once a downgrade takes effect, runs already going finish at the standard pace and new ones are refused.
curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"workflow": "<string>",
"input": {},
"reference": "order-1042",
"version": "<string>",
"webhook_url": "<string>"
}
'import requests
url = "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs"
payload = {
"workflow": "<string>",
"input": {},
"reference": "order-1042",
"version": "<string>",
"webhook_url": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
workflow: '<string>',
input: {},
reference: 'order-1042',
version: '<string>',
webhook_url: '<string>'
})
};
fetch('https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'workflow' => '<string>',
'input' => [
],
'reference' => 'order-1042',
'version' => '<string>',
'webhook_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs"
payload := strings.NewReader("{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://qubesync.com/api/v2/connections/{connection_id}/workflow-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"workflow\": \"<string>\",\n \"input\": {},\n \"reference\": \"order-1042\",\n \"version\": \"<string>\",\n \"webhook_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"cancel_reason": "<string>",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"current_state": "create_customer / resolve_conflict.find_holder",
"error": {
"code": 3100,
"hint": "<string>",
"message": "<string>",
"quickbooks_message": "<string>",
"type": "name_in_use"
},
"headline": "Created Riverbend Electric in QuickBooks.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"input": {},
"links": {
"cancel": "<string>",
"decisions": "<string>",
"search": "<string>",
"self": "<string>",
"ui": "<string>"
},
"outcome": "<string>",
"output": {},
"prompt": {
"choices": [
{
"description": "Try the add again under a name you choose.",
"detail": "Customer · similar name",
"fields": [
{
"label": "New name",
"name": "name",
"required": true,
"type": "string",
"columns": [
{
"enum": [
{
"label": "Service",
"value": "item_service"
}
],
"kind": "account",
"label": "Income account",
"name": "income_account",
"required": true,
"type": "string",
"when": {
"action": [
"create"
]
}
}
],
"enum": [
{
"label": "Service",
"value": "item_service"
}
],
"kind": "customer",
"rows": [
{
"columns": [
"action",
"list_id",
"income_account"
],
"detail": "Item",
"key": "invoice_line_add.0.item_ref",
"kinds": {
"income_account": "account",
"list_id": "item"
},
"label": "Vinyl Banner",
"values": {
"item_type": "item_non_inventory"
}
}
]
}
],
"id": "rename",
"label": "Add it under another name"
}
],
"details": [
{
"label": "Customer",
"value": "Lone Star Supply Co"
}
],
"kind": "decision",
"token": "<string>"
},
"reference": "<string>",
"revision": 2,
"state": "running",
"summary": {
"calls": [
{
"item_index": 123,
"outcome": "<string>",
"state": "create_customer",
"status": "completed",
"workflow": "<string>"
}
],
"changes": [
{
"action": "create",
"kind": "customer",
"full_name": "<string>",
"item": 123,
"list_id": "<string>",
"ref_number": "<string>",
"settled": "found",
"txn_id": "<string>"
}
],
"decisions": [
{
"at": "2023-11-07T05:31:56Z",
"item_index": 123,
"option": "<string>",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"discarded": [
{
"item_index": 123,
"items_not_started": 123,
"message": "<string>",
"operation": "<string>",
"queued_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"ended_at": "2023-11-07T05:31:56Z",
"matches": [
{
"candidates": 123,
"candidates_total": 123,
"candidates_total_complete": true,
"index": "ready",
"item_index": 123,
"match": "exact",
"state": "<string>",
"workflow": "<string>"
}
],
"notifications": {
"failed": 123,
"sent": 123
},
"requests": [
{
"evidence": "of 2 candidates with reference number \"1044\", one carries the GUID sent (txn_id 2-1), so the add was applied",
"found_by": "look_for_invoice",
"identifiers": {
"full_name": "<string>",
"list_id": "<string>",
"ref_number": "<string>",
"txn_id": "<string>"
},
"item_index": 123,
"operation": "<string>",
"pages": 123,
"role": "prepare",
"settled": "found",
"state": "create_customer / try_create",
"status": "success",
"unconfirmed": true,
"workflow": "<string>"
}
],
"side_effects": [
{
"evidence": "<string>",
"identifiers": {
"full_name": "<string>",
"list_id": "<string>",
"ref_number": "<string>",
"txn_id": "<string>"
},
"item_index": 123,
"operation": "<string>",
"settled": "found",
"state": "create_customer / try_create",
"workflow": "<string>"
}
],
"stopped_at": "create_customer / resolve_conflict.ask_about_customer",
"unconfirmed": [
{
"item_index": 123,
"operation": "<string>",
"state": "add_invoice",
"workflow": "<string>"
}
]
},
"trace": [
{
"at": "2023-11-07T05:31:56Z",
"event": "<string>",
"from": "<string>",
"to": "<string>"
}
],
"vars": {},
"workflow": "<string>"
}
}Authorizations
Use your app's API key as the username, and leave the password blank
Headers
Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers 201 with what the first call created, as it is now, marked Idempotent-Replayed: true, and queues nothing. The same key with a different request is a 422. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters.
1 - 255^[\x20-\x7E]+$Path Parameters
ID of the connection
Body
The workflow's key
Matches the workflow's own input_schema
Your own label for the run, such as the id of the record it is about: kept exactly as sent, never changed, and returned on the run and in every webhook it sends (reference), so you can match a webhook to your record before you have the run's id. Not unique -- starting two runs with one reference is allowed, and GET .../workflow-runs?reference= lists both; Idempotency-Key is what makes a start happen once. Give every run its own (order-1042-2 for a second run about order-1042): revisions count per run, so a second run's bodies, found by the first run's reference, would be skipped against the first run's revision. One that is empty, longer than 255 characters or not a string is a 422 field by field, {"errors": {"reference": [...]}}.
1 - 255"order-1042"
Which chart to run: published, working or a version number. Only a choice on a sandbox connection: a production connection always runs the published version, and refuses working or a number with a 422.
An absolute http or https URL where the run's webhooks go: workflow_run.awaiting_input, its ending, and workflow_run.notification from notify states. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A qube listen URL must be one of this app's. Required for a workflow that sends the app data (a notify state, its own or in a workflow it calls): without it, 422 webhook_url_required; one that breaks these rules is a 422 field by field, {"errors": {"webhook_url": [...]}}.
2048Response
The run was started
Show child attributes
Show child attributes