cURL

curl --request GET \
  --url https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions', 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://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "attributes": {
        "status": "<string>",
        "current_step": "<string>",
        "started_at": "2023-11-07T05:31:56Z",
        "finished_at": "2023-11-07T05:31:56Z",
        "elapsed_minutes": 123,
        "step_count": 123,
        "returned": true,
        "stages": [
          {
            "from": {
              "id": "<string>",
              "name": "<string>"
            },
            "to": {
              "id": "<string>",
              "name": "<string>",
              "status": "<string>"
            },
            "at": "2023-11-07T05:31:56Z",
            "operator": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "minutes_in_step": 123,
            "note": "<string>"
          }
        ]
      },
      "relationships": {
        "submission": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        },
        "operators": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "definition": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        }
      }
    }
  ],
  "jsonapi": {
    "version": "<string>"
  },
  "meta": {
    "pagination": {
      "counts": {
        "pages": 123,
        "resources": 123
      },
      "current_page": 123,
      "offsets": {
        "next": 123,
        "previous": 123
      },
      "requested": {
        "limit": 123,
        "offset": 123
      }
    },
    "features": {
      "include": {
        "options": [
          "<string>"
        ]
      }
    },
    "stats": {
      "truncated": true
    }
  },
  "included": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "attributes": {
        "email": "jsmith@example.com",
        "identities": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "platform": "<string>",
            "meta": {}
          }
        ],
        "profile": {
          "work": {
            "occupation": "<string>",
            "cscs": "<string>",
            "eusr": "<string>",
            "start_date": "2023-12-25"
          },
          "personal": {
            "first_name": "<string>",
            "last_name": "<string>",
            "dob": "2023-12-25",
            "username": "<string>"
          },
          "contact": {
            "mobile": "<string>",
            "landline": "<string>"
          },
          "address": {
            "number": "",
            "street": "<string>",
            "area": "<string>",
            "town": "<string>",
            "county": "<string>",
            "postcode": "<string>",
            "country_code": "<string>",
            "what3words": "<string>"
          },
          "settings": {
            "preferred_language": "en-GB",
            "timezone": "<string>"
          }
        }
      },
      "meta": {},
      "relationships": {
        "organisations": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "teams": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "managing_organisation": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        }
      }
    }
  ]
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Workflows

List workflow submission journeys

The per-submission journeys behind the aggregate figures: for each submission that transitioned inside the window, its status, current step, start and finish, elapsed time, step count, whether it was sent back, and every stage it passed through. The operators are side-loaded, so their names are available without a second read.

Takes the same required window and the same optional cohort filters as the aggregate, so a page of journeys always reconciles with the figures above it.

Send Accept: text/csv (or format=csv) for the export instead of a page: shape=transitions for one row per transition, shape=summary for one row per submission. The export ignores pagination and covers the whole window.

A window the server had to bound is reported as meta.stats.truncated on the JSON response, and as an X-Insights-Truncated header on the export, where a spreadsheet cannot carry the caveat itself.

Served by a hand-written handler rather than a generated one, because the resource is computed rather than stored.

GET

workflow-definitions

{workflow_definition_id}

insights

submissions

cURL

curl --request GET \
  --url https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions \
  --header 'X-Session-Token: <api-key>'

import requests

url = "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions"

headers = {"X-Session-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions', 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://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/workflow-definitions/{workflow_definition_id}/insights/submissions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "attributes": {
        "status": "<string>",
        "current_step": "<string>",
        "started_at": "2023-11-07T05:31:56Z",
        "finished_at": "2023-11-07T05:31:56Z",
        "elapsed_minutes": 123,
        "step_count": 123,
        "returned": true,
        "stages": [
          {
            "from": {
              "id": "<string>",
              "name": "<string>"
            },
            "to": {
              "id": "<string>",
              "name": "<string>",
              "status": "<string>"
            },
            "at": "2023-11-07T05:31:56Z",
            "operator": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "minutes_in_step": 123,
            "note": "<string>"
          }
        ]
      },
      "relationships": {
        "submission": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        },
        "operators": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "definition": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        }
      }
    }
  ],
  "jsonapi": {
    "version": "<string>"
  },
  "meta": {
    "pagination": {
      "counts": {
        "pages": 123,
        "resources": 123
      },
      "current_page": 123,
      "offsets": {
        "next": 123,
        "previous": 123
      },
      "requested": {
        "limit": 123,
        "offset": 123
      }
    },
    "features": {
      "include": {
        "options": [
          "<string>"
        ]
      }
    },
    "stats": {
      "truncated": true
    }
  },
  "included": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "attributes": {
        "email": "jsmith@example.com",
        "identities": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "platform": "<string>",
            "meta": {}
          }
        ],
        "profile": {
          "work": {
            "occupation": "<string>",
            "cscs": "<string>",
            "eusr": "<string>",
            "start_date": "2023-12-25"
          },
          "personal": {
            "first_name": "<string>",
            "last_name": "<string>",
            "dob": "2023-12-25",
            "username": "<string>"
          },
          "contact": {
            "mobile": "<string>",
            "landline": "<string>"
          },
          "address": {
            "number": "",
            "street": "<string>",
            "area": "<string>",
            "town": "<string>",
            "county": "<string>",
            "postcode": "<string>",
            "country_code": "<string>",
            "what3words": "<string>"
          },
          "settings": {
            "preferred_language": "en-GB",
            "timezone": "<string>"
          }
        }
      },
      "meta": {},
      "relationships": {
        "organisations": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "teams": {
          "data": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "type": "<string>"
            }
          ]
        },
        "managing_organisation": {
          "data": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "type": "<string>"
          }
        }
      }
    }
  ]
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "id": "7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f",
  "status": "404",
  "title": "Resource not found",
  "detail": "The requested resource could not be found or does not exist.",
  "code": "NOT_FOUND.001"
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Authorizations

X-Session-Token

string

header

required

Session token for authentication.

Path Parameters

workflow_definition_id

string<uuid>

required

The unique identifier for the workflow.

Query Parameters

filter

string

required

Narrows the transition records the figures are computed from.

The reporting window is required — an unbounded window would mean aggregating the whole collection, so it is rejected rather than served:

ge(created_at,xxx): the start of the window. Required.
le(created_at,xxx): the end of the window. Required.

The cohort filters are optional and mutually exclusive. Both resolve to a set of submissions server-side, through the operation a submission captured:

eq(scheme,xxx): only submissions whose payload operation belongs to the scheme.
eq(contract,xxx): as scheme, expanded across every scheme in the contract.

A submission that captured no operation cannot join a scheme or a contract, so it is invisible to both cohorts. Unscoped figures include it.

The organisation is not a filter — it is the organisation that owns the workflow definition in the path.

For more information on using named filters, see the docs

Minimum string length: 1

sort

enum<string>[]

The field to order the journeys by. One field only, and the schema refuses a second: there is no secondary sort behind it, so a second value would have had no effect on the order it came back in.

Defaults to -started_at, the most recently started first. Submissions still in progress have no elapsed time, so they sort last under both elapsed_minutes and -elapsed_minutes.

Maximum array length: 1

Available options:

started_at,

-started_at,

elapsed_minutes,

-elapsed_minutes

limit

integer<int64>

default:100

Limit the number of resources returned by the API

Required range: x >= 1

offset

integer<int64>

default:0

Offset the resources returned by the API

Required range: x >= 0

format

enum<string>

Asks for the CSV export rather than a page of journeys. format=csv is equivalent to sending Accept: text/csv, and exists so the export is a plain URL — the form a browser download or a scheduled delivery can use without setting a header.

Available options:

csv

shape

enum<string>

default:transitions

The shape of the CSV export. transitions writes one row per transition — the stage-by-stage trail behind each submission. summary writes one row per submission. Ignored unless CSV was asked for.

Available options:

transitions,

summary

Response

A page of the workflow's submission journeys, or the whole set as CSV when text/csv was asked for.

Document level meta about the resources on the server in list endpoints.

data

A list of workflow submission journeys · object[]

required

Show child attributes

jsonapi

object

required

Show child attributes