Partially update a customSchema#

Deprecated

This endpoint is deprecated and may be removed in a future release.

This endpoint was deprecated on 2026-02-12.

It is scheduled for sunset on 2027-01-31.

Description#

Partially update the schema of custom fields and custom field groups for the entire workspace.

Note: This endpoint is rate-limited. You may experience rates as low as 60 requests per minute. This limit is enforced per workspace and is inclusive of both API and UI based requests. When polling for updates, examine the Retry-After header and retry after that many seconds.

PATCH /prototype/platform/customSchema

Required OAuth Scopes

file:write

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	false	Version of the API (2022-01-01)
body	body	JSONPatchDocument	true	JSON Patch document to be atomically applied to the custom schema. All valid patch operations are supported, although the operation will error if read-only properties are changed by the patch. Refer to the schema for documentation about which properties are read-only.

Detailed descriptions#

body: JSON Patch document to be atomically applied to the custom schema. All valid patch operations are supported, although the operation will error if read-only properties are changed by the patch. Refer to the schema for documentation about which properties are read-only.

User-defined custom fields and groups can be added, modified, and removed, but certain state change transition rules must also be obeyed:

Custom field ids must be unique within the workspace regardless of case and cannot be changed after creation. However, the display ‘title’ in the schema of a field can be changed.
Custom field group ids must be unique within the workspace regardless of case and cannot be changed after creation. However, the display ‘name’ of a group can be changed.
Once a custom field is transitioned out of ‘draft’ state, it cannot be transitioned back to ‘draft’ state or removed.
The top-level properties of the custom schema cannot be added or removed.
A custom field group must be user defined or built-in, but cannot be both or neither. The type of a group cannot be changed after creation.
Builtin custom field groups are provided by the Workiva Platform and cannot be added, modified, or removed.

NOTE: When adding or removing elements from a list, it is necessary to use a ‘test’ operation followed by a ‘replace’ operation to swap the entire list with a new list that includes the desired changes. The order of the lists is not guaranteed.

Possible error codes in the response:

read_only: Changing the requested read-only property is not allowed.
remove_unsupported: Removing the requested element is not allowed.
missing_subtype: The patch resulted in an object without a required subtype.
multiple_subtypes: The patch resulted in an object multiple subtypes, but only one is allowed.
changed_subtype: The requested change attempted to change the subtype of an existing object, which is not allowed.
backwards_incompatible: The requested change was valid, but cannot be applied because it would be backwards-incompatible.
cannot_create_builtin: The request to create a builtin custom field or group is not allowed.
cannot_apply_patch: The requested change was valid but could not be applied to the data due to the semantics defined for JSON Patch.
invalid_result: The patch would have resulted in data that is not valid.
identifier_conflict: The patch would have resulted in a case-insensitive conflict with an existing identifier.

Body parameter example#

[
  {
    "op": "replace",
    "path": "/name",
    "value": "New name"
  }
]

Code Samples#

curl

curl -X PATCH https://api.app.wdesk.com/prototype/platform/customSchema \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'X-Version: 2022-01-01'

httpie

http PATCH https://api.app.wdesk.com/prototype/platform/customSchema \
    X-Version:2022-01-01 \
    Content-Type:application/json \
    Accept:application/json \
    Authorization:"Bearer {access-token}"

wget

wget --method=PATCH "https://api.app.wdesk.com/prototype/platform/customSchema" \
    --output-document -  \ 
    --header 'Content-Type: application/json' \ 
    --header 'Accept: application/json' \ 
    --header 'Authorization: Bearer {access-token}' \
    --header 'X-Version: 2022-01-01'

python

import requests

headers = {
  'X-Version': '2022-01-01',
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api.app.wdesk.com/prototype/platform/customSchema', headers = headers)

print(r.json())