Update an organisation's document settings
curl --request PATCH \
--url https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Session-Token: <api-key>' \
--data '
{
"data": {
"type": "document-settings",
"attributes": {
"expiry_threshold_days": [
7,
30
],
"expiry_recipient_teams": [
"b234c567-8901-2345-6789-abcdef012345"
]
}
}
}
'import requests
url = "https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents"
payload = { "data": {
"type": "document-settings",
"attributes": {
"expiry_threshold_days": [7, 30],
"expiry_recipient_teams": ["b234c567-8901-2345-6789-abcdef012345"]
}
} }
headers = {
"X-Session-Token": "<api-key>",
"Content-Type": "application/vnd.api+json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-Session-Token': '<api-key>', 'Content-Type': 'application/vnd.api+json'},
body: JSON.stringify({
data: {
type: 'document-settings',
attributes: {
expiry_threshold_days: [7, 30],
expiry_recipient_teams: ['b234c567-8901-2345-6789-abcdef012345']
}
}
})
};
fetch('https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents', 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/orgs/{org_id}/settings/documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'type' => 'document-settings',
'attributes' => [
'expiry_threshold_days' => [
7,
30
],
'expiry_recipient_teams' => [
'b234c567-8901-2345-6789-abcdef012345'
]
]
]
]),
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/orgs/{org_id}/settings/documents"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents")
.header("X-Session-Token", "<api-key>")
.header("Content-Type", "application/vnd.api+json")
.body("{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Session-Token"] = '<api-key>'
request["Content-Type"] = 'application/vnd.api+json'
request.body = "{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations",
"attributes": {
"name": "Acme Construction Ltd",
"slug": "acme-construction",
"sandbox": false,
"description": "Leading construction company specializing in infrastructure projects",
"settings": {
"documents": {
"expiry_threshold_days": [
7,
30
],
"expiry_recipient_teams": [
"b234c567-8901-2345-6789-abcdef012345"
]
},
"calendar": {
"bank_holiday_nation": "england-and-wales"
},
"teams": {
"customer_representatives": [
"b234c567-8901-2345-6789-abcdef012345"
]
},
"security": {
"require_mfa": false
}
}
},
"meta": {
"v3": true,
"status": "active",
"created_at": "2023-01-15T10:30:00.000Z",
"updated_at": "2023-02-20T14:45:00.000Z",
"features": [
{
"name": "advanced_reporting",
"enabled": true,
"limit": 1000
}
]
},
"relationships": {
"users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"service_accounts": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "service-accounts"
}
]
},
"groups": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "groups"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"nomenclature": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature",
"attributes": {
"governance": {
"schemes": [
{
"singular": "Project",
"plural": "Projects",
"language": "en-GB"
}
],
"work_orders": [
{
"singular": "Work Order",
"plural": "Work Orders",
"language": "en-GB"
}
],
"operations": [
{
"singular": "Operation",
"plural": "Operations",
"language": "en-GB"
}
],
"scheme_contracts": [
{
"singular": "Contract",
"plural": "Contracts",
"language": "en-GB"
}
]
}
},
"meta": {
"created_at": "2023-10-01T12:00:00.000Z",
"updated_at": "2023-10-01T12:00:00.000Z"
}
}
]
}{
"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."
}Organisations
Update organisation document settings
Replace the document-settings sub-resource for an organisation: who is
notified before a document expires, and how far ahead. The supplied lists
replace whatever was previously stored. Thresholds are stored in ascending
order. Each referenced team must belong to the organisation identified in
the path. With no teams, nobody is notified. Requires the
document-settings:update permission, granted organisation-wide.
PATCH
/
v3
/
orgs
/
{org_id}
/
settings
/
documents
Update an organisation's document settings
curl --request PATCH \
--url https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents \
--header 'Content-Type: application/vnd.api+json' \
--header 'X-Session-Token: <api-key>' \
--data '
{
"data": {
"type": "document-settings",
"attributes": {
"expiry_threshold_days": [
7,
30
],
"expiry_recipient_teams": [
"b234c567-8901-2345-6789-abcdef012345"
]
}
}
}
'import requests
url = "https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents"
payload = { "data": {
"type": "document-settings",
"attributes": {
"expiry_threshold_days": [7, 30],
"expiry_recipient_teams": ["b234c567-8901-2345-6789-abcdef012345"]
}
} }
headers = {
"X-Session-Token": "<api-key>",
"Content-Type": "application/vnd.api+json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-Session-Token': '<api-key>', 'Content-Type': 'application/vnd.api+json'},
body: JSON.stringify({
data: {
type: 'document-settings',
attributes: {
expiry_threshold_days: [7, 30],
expiry_recipient_teams: ['b234c567-8901-2345-6789-abcdef012345']
}
}
})
};
fetch('https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents', 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/orgs/{org_id}/settings/documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'type' => 'document-settings',
'attributes' => [
'expiry_threshold_days' => [
7,
30
],
'expiry_recipient_teams' => [
'b234c567-8901-2345-6789-abcdef012345'
]
]
]
]),
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/orgs/{org_id}/settings/documents"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents")
.header("X-Session-Token", "<api-key>")
.header("Content-Type", "application/vnd.api+json")
.body("{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/orgs/{org_id}/settings/documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Session-Token"] = '<api-key>'
request["Content-Type"] = 'application/vnd.api+json'
request.body = "{\n \"data\": {\n \"type\": \"document-settings\",\n \"attributes\": {\n \"expiry_threshold_days\": [\n 7,\n 30\n ],\n \"expiry_recipient_teams\": [\n \"b234c567-8901-2345-6789-abcdef012345\"\n ]\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "organisations",
"attributes": {
"name": "Acme Construction Ltd",
"slug": "acme-construction",
"sandbox": false,
"description": "Leading construction company specializing in infrastructure projects",
"settings": {
"documents": {
"expiry_threshold_days": [
7,
30
],
"expiry_recipient_teams": [
"b234c567-8901-2345-6789-abcdef012345"
]
},
"calendar": {
"bank_holiday_nation": "england-and-wales"
},
"teams": {
"customer_representatives": [
"b234c567-8901-2345-6789-abcdef012345"
]
},
"security": {
"require_mfa": false
}
}
},
"meta": {
"v3": true,
"status": "active",
"created_at": "2023-01-15T10:30:00.000Z",
"updated_at": "2023-02-20T14:45:00.000Z",
"features": [
{
"name": "advanced_reporting",
"enabled": true,
"limit": 1000
}
]
},
"relationships": {
"users": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "users"
}
]
},
"service_accounts": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "service-accounts"
}
]
},
"groups": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "groups"
}
]
},
"teams": {
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "teams"
}
]
},
"nomenclature": {
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature"
}
}
}
},
"jsonapi": {
"version": "1.0"
},
"included": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "nomenclature",
"attributes": {
"governance": {
"schemes": [
{
"singular": "Project",
"plural": "Projects",
"language": "en-GB"
}
],
"work_orders": [
{
"singular": "Work Order",
"plural": "Work Orders",
"language": "en-GB"
}
],
"operations": [
{
"singular": "Operation",
"plural": "Operations",
"language": "en-GB"
}
],
"scheme_contracts": [
{
"singular": "Contract",
"plural": "Contracts",
"language": "en-GB"
}
]
}
},
"meta": {
"created_at": "2023-10-01T12:00:00.000Z",
"updated_at": "2023-10-01T12:00:00.000Z"
}
}
]
}{
"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
Body
application/vnd.api+json
The document-settings for the organisation to update.