Create a new action
curl --request POST \
--url https://api.ctrl-hub.com/v3/actions \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Session-Token: <api-key>' \
--data '
{
"data": {
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"body": "<string>",
"priority": "high",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"assigned_users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
}
}
}
}
'import requests
url = "https://api.ctrl-hub.com/v3/actions"
payload = { "data": {
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"body": "<string>",
"priority": "high",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"relationships": {
"organisation": { "data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
} },
"assigned_users": { "data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
] }
}
} }
headers = {
"X-Session-Token": "<api-key>",
"Content-Type": "application/vnd.api+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-Token': '<api-key>', 'Content-Type': 'application/vnd.api+json'},
body: JSON.stringify({
data: {
type: 'actions',
attributes: {
title: 'Review submission for Scheme Alpha',
body: JSON.stringify('<string>'),
priority: 'high',
subject_type: 'form-submissions',
due_at: '2026-06-05T17:00:00.000Z'
},
relationships: {
organisation: {data: {id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', type: 'organisations'}},
assigned_users: {data: [{id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', type: 'users'}]}
}
}
})
};
fetch('https://api.ctrl-hub.com/v3/actions', 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/actions",
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([
'data' => [
'type' => 'actions',
'attributes' => [
'title' => 'Review submission for Scheme Alpha',
'body' => '<string>',
'priority' => 'high',
'subject_type' => 'form-submissions',
'due_at' => '2026-06-05T17:00:00.000Z'
],
'relationships' => [
'organisation' => [
'data' => [
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'type' => 'organisations'
]
],
'assigned_users' => [
'data' => [
[
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'type' => 'users'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/vnd.api+json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/actions"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-Token", "<api-key>")
req.Header.Add("Content-Type", "application/vnd.api+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://api.ctrl-hub.com/v3/actions")
.header("X-Session-Token", "<api-key>")
.header("Content-Type", "application/vnd.api+json")
.body("{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-Token"] = '<api-key>'
request["Content-Type"] = 'application/vnd.api+json'
request.body = "{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"priority": "high",
"state": "open",
"body": "Submission",
"close_reason": "completed",
"closed_at": "2023-11-07T05:31:56Z",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"meta": {
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"deleted_at": "2023-11-07T05:31:56Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"assigned_users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"assigned_teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"form_submission": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "form-submissions"
}
},
"triggering_job_role": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "job-roles"
}
},
"closed_by": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"type": "users",
"attributes": {
"email": "john.doe@example.com",
"status": "active",
"identities": [
{
"id": "39ce13b8-1116-416a-ad5f-3c5edfd44f53",
"platform": "multi_tenant",
"meta": {}
}
],
"profile": {
"work": {
"occupation": "Site Manager",
"cscs": "CSC123456",
"eusr": "EUR789123",
"start_date": "2020-03-01T00:00:00.000Z"
},
"personal": {
"first_name": "John",
"last_name": "Doe",
"dob": "1985-06-15T00:00:00.000Z",
"username": "johndoe"
},
"contact": {
"mobile": "+44 7700 900123",
"landline": "+44 20 7946 0958"
},
"address": {
"number": "42",
"street": "High Street",
"area": "Westminster",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"country_code": "GB",
"what3words": "filled.count.soap"
},
"settings": {
"preferred_language": "en-GB",
"timezone": "Europe/London"
}
}
},
"meta": {
"managed_type": "none"
},
"relationships": {
"organisations": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"managing_organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
}
}
}
]
}{
"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."
}Actions
Create an action
Create a new action assigned to one or more users and/or teams. Primarily driven by producers (such as the data-capture workflow subscriber) but also available for manual / administrative creation.
POST
/
v3
/
actions
Create a new action
curl --request POST \
--url https://api.ctrl-hub.com/v3/actions \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Session-Token: <api-key>' \
--data '
{
"data": {
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"body": "<string>",
"priority": "high",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"assigned_users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
}
}
}
}
'import requests
url = "https://api.ctrl-hub.com/v3/actions"
payload = { "data": {
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"body": "<string>",
"priority": "high",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"relationships": {
"organisation": { "data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
} },
"assigned_users": { "data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
] }
}
} }
headers = {
"X-Session-Token": "<api-key>",
"Content-Type": "application/vnd.api+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-Token': '<api-key>', 'Content-Type': 'application/vnd.api+json'},
body: JSON.stringify({
data: {
type: 'actions',
attributes: {
title: 'Review submission for Scheme Alpha',
body: JSON.stringify('<string>'),
priority: 'high',
subject_type: 'form-submissions',
due_at: '2026-06-05T17:00:00.000Z'
},
relationships: {
organisation: {data: {id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', type: 'organisations'}},
assigned_users: {data: [{id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', type: 'users'}]}
}
}
})
};
fetch('https://api.ctrl-hub.com/v3/actions', 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/actions",
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([
'data' => [
'type' => 'actions',
'attributes' => [
'title' => 'Review submission for Scheme Alpha',
'body' => '<string>',
'priority' => 'high',
'subject_type' => 'form-submissions',
'due_at' => '2026-06-05T17:00:00.000Z'
],
'relationships' => [
'organisation' => [
'data' => [
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'type' => 'organisations'
]
],
'assigned_users' => [
'data' => [
[
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'type' => 'users'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/vnd.api+json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/actions"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-Token", "<api-key>")
req.Header.Add("Content-Type", "application/vnd.api+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://api.ctrl-hub.com/v3/actions")
.header("X-Session-Token", "<api-key>")
.header("Content-Type", "application/vnd.api+json")
.body("{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-Token"] = '<api-key>'
request["Content-Type"] = 'application/vnd.api+json'
request.body = "{\n \"data\": {\n \"type\": \"actions\",\n \"attributes\": {\n \"title\": \"Review submission for Scheme Alpha\",\n \"body\": \"<string>\",\n \"priority\": \"high\",\n \"subject_type\": \"form-submissions\",\n \"due_at\": \"2026-06-05T17:00:00.000Z\"\n },\n \"relationships\": {\n \"organisation\": {\n \"data\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"organisations\"\n }\n },\n \"assigned_users\": {\n \"data\": [\n {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"type\": \"users\"\n }\n ]\n }\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "actions",
"attributes": {
"title": "Review submission for Scheme Alpha",
"priority": "high",
"state": "open",
"body": "Submission",
"close_reason": "completed",
"closed_at": "2023-11-07T05:31:56Z",
"subject_type": "form-submissions",
"due_at": "2026-06-05T17:00:00.000Z"
},
"meta": {
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"deleted_at": "2023-11-07T05:31:56Z"
},
"relationships": {
"organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
},
"assigned_users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"assigned_teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"form_submission": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "form-submissions"
}
},
"triggering_job_role": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "job-roles"
}
},
"closed_by": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"type": "users",
"attributes": {
"email": "john.doe@example.com",
"status": "active",
"identities": [
{
"id": "39ce13b8-1116-416a-ad5f-3c5edfd44f53",
"platform": "multi_tenant",
"meta": {}
}
],
"profile": {
"work": {
"occupation": "Site Manager",
"cscs": "CSC123456",
"eusr": "EUR789123",
"start_date": "2020-03-01T00:00:00.000Z"
},
"personal": {
"first_name": "John",
"last_name": "Doe",
"dob": "1985-06-15T00:00:00.000Z",
"username": "johndoe"
},
"contact": {
"mobile": "+44 7700 900123",
"landline": "+44 20 7946 0958"
},
"address": {
"number": "42",
"street": "High Street",
"area": "Westminster",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"country_code": "GB",
"what3words": "filled.count.soap"
},
"settings": {
"preferred_language": "en-GB",
"timezone": "Europe/London"
}
}
},
"meta": {
"managed_type": "none"
},
"relationships": {
"organisations": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"managing_organisation": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations"
}
}
}
}
]
}{
"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
SessionOAuth2Cookie
Session token for authentication.
Query Parameters
A comma separated list of related resources to include.
Available options:
assigned_users, assigned_teams, form_submission, triggering_job_role, closed_by Body
application/vnd.api+json
The action to create. organisation is required. At least one assignee must
be provided across assigned_users and assigned_teams. form_submission
and triggering_job_role are optional; when subject_type is set to
form-submissions the form_submission relationship should be populated.
Show child attributes
Show child attributes
Response
Action created successfully.
JSON API response object
An action is a piece of work that needs doing, assigned to one or more users
and/or teams. It has a lifecycle state (open / closed), a priority, an
optional due date, and an optional polymorphic link back to whatever produced
it (in v1, a form submission). Actions are produced both manually and by
domain producers such as the data-capture workflow runner.
The subject is optional. When present, exactly the relationship matching
subject_type is populated (v1: subject_type is form-submissions, so
form_submission is the populated relationship). Manual actions can have no
subject at all.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Related resources that can be included when an action is returned.
A user
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes