Workspace settings API

GET and PUT /api/v1/settings/workspace read and change the controls that apply to the whole workspace. They are what Settings → Workspace uses; for what each setting does and when it takes effect, see Workspace settings.

Before you start

Who can call it. A signed-in person with settings.manage (by default the Administrator). Anyone else gets 403 missing permission settings.manage.

Signing in with curl. Sign in once and keep the session cookie in a file, as described in Alerts and cases API: before you start, then add -b ~/.sp-cookies to the requests below.

The settings object

Both endpoints return the same object:

{
  "name": "Acme Pay",
  "country": "GH",
  "base_currency": "GHS",
  "timezone": "Africa/Accra",
  "default_locale": "en",
  "require_mfa": true,
  "revoke_api_keys_on_deactivation": false,
  "four_eyes_all_closures": false,
  "case_sla_hours": { "critical": 4, "high": 24, "medium": 72, "low": 168 },
  "decisions": { "failure_mode": "open", "timeout_ms": 150, "review_score": 0, "block_score": 0,
                 "sanctions_confirmed": "block", "sanctions_pending": "review" },
  "jurisdiction": "gh",
  "jurisdiction_picked": false,
  "identifier_validation": "warn"
}

Field	Type	Meaning	Allowed values	Default
`name`	string	The institution’s display name	2 to 120 characters	Set at creation
`country`	string	Two-letter country code. Read-only		Set at creation
`base_currency`	string	Currency every amount is converted into. Read-only		Set at creation
`timezone`	string	IANA time zone for calendar-day rules, dashboards, deadline messages and zone-less CSV import times	A real IANA name, such as `Africa/Lagos`. Not `Local`	Set at creation
`default_locale`	string	Language of the screens and of notifications for people who haven’t chosen one. See Languages	`en`, `fr`	Set at creation
`require_mfa`	boolean	Everyone must use an authenticator app		`true`
`revoke_api_keys_on_deactivation`	boolean	When someone is deactivated, revoke the API keys they created at once instead of marking them rotation due. See Managing API keys		`false`
`four_eyes_all_closures`	boolean	Every case closure needs a second approver, not only high and critical		`false`
`case_sla_hours`	object	Hours to resolve a case, by priority: `critical`, `high`, `medium`, `low`. An escalation policy level with its own `sla_minutes` overrides it for cases at that level	Each 1 to 2160; fractions allowed. Must not get longer as priority rises	4, 24, 72, 168
`decisions.failure_mode`	string	Answer when a real-time decision can’t finish in time: `open` allows it and flags it for review afterwards, `closed` answers review	`open`, `closed`	`open`
`decisions.timeout_ms`	integer	Server-side time budget for one decision, in milliseconds	20 to 2000	`150`
`decisions.review_score`	number	Combined score at which a payment is at least reviewed. `0` turns it off	0 to 100	`0`
`decisions.block_score`	number	Combined score at which a payment is blocked. `0` turns it off	0 to 100, and at least `review_score` when both are above 0	`0`
`decisions.sanctions_confirmed`	string	What a decision answers when the customer or counterparty is a confirmed sanctions match whose designation is in force. Applied after the rules; no `allow` rule waives it. Left out of a `PUT`, it keeps its current value	`block`, `review`, `off` (leave it to the rules)	`block`
`decisions.sanctions_pending`	string	The same for an open, undecided potential sanctions match, including one found by screening a new counterparty’s name inside the decision	`review`, `block`, `off`	`review`
`jurisdiction`	string	The jurisdiction the workspace follows. Empty or left out in an update: unchanged	A code from `GET /api/v1/jurisdictions` whose currency is the workspace’s base currency, or `global`	The country’s
`jurisdiction_picked`	boolean	`false` while the workspace follows its country’s definition without having picked one. Read-only
`identifier_validation`	string	What ingest does with a national identifier that doesn’t fit its format. Empty or left out: unchanged	`warn`, `reject`, `off`	`warn`

`GET /api/v1/settings/workspace`

Returns the settings object. Settings never changed come back with their defaults. So does any stored value that can’t be used: for example, a case deadline that is missing or zero comes back as that priority’s default, and case work uses the same default rather than failing.

curl -s -b ~/.sp-cookies "$SP/api/v1/settings/workspace"

`PUT /api/v1/settings/workspace`

Replaces every editable setting at once, and returns the settings object as saved.


Permission	`settings.manage`
Body	The whole settings object. Every field except `country` and `base_currency` is required
Read-only fields	`country` and `base_currency` may be sent back unchanged or left out; any value you send is ignored
Audit	`tenant.settings`, with every setting before and after

How to change one setting. Read the settings, change the field, and send the whole object back:

curl -s -b ~/.sp-cookies "$SP/api/v1/settings/workspace" \
  | jq '.four_eyes_all_closures = true' \
  | curl -s -b ~/.sp-cookies -X PUT -H 'Content-Type: application/json' \
      --data-binary @- "$SP/api/v1/settings/workspace"

Errors

Status	When	Example `detail`
`401`	Not signed in, or an API key	`sign in required`
`403`	Missing `settings.manage`	`missing permission settings.manage`
`422`	A field is missing, unknown, has the wrong type, or is out of range. The `errors` list names the field, such as `body.case_sla_hours.critical`	`validation failed`
`422`	The time zone isn’t a real IANA name	`invalid setting: "Africa/Akra" is not an IANA timezone`
`422`	A higher priority has a longer deadline	`invalid setting: case SLAs must not get longer as priority rises (critical ≤ high ≤ medium ≤ low)`
`422`	`block_score` is below `review_score`, both above 0	`invalid setting: the block score must be at least the review score`
`422`	The jurisdiction is unknown, a region, or in another currency	`invalid setting: Nigeria uses NGN, but this workspace's base currency is GHS`