Custom Field Definitions

Custom Field Definitions describe the schema - name, required, type, options, entity placements, and framework scope - of the Custom Fields configured on your account. Use them to discover the option IDs required to write OPTIONS values via the API.

List Custom Field Definitions

Returns the Custom Field Definitions configured for this account.

🔒 Requires Custom Field Definitions: Get Custom Field Definitions permission.

💎 Requires your account have the Custom Fields and Formulas feature. Contact your CSM for help upgrading.

Securitybearer
Request
query Parameters
cursor
string

This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results

size
number [ 1 .. 500 ]
Default: 50

Number of results to return

sort
string (SortTypeLimitedEnum)

Which field to sort by

Enum: "createdAt" "updatedAt"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
entityType
string (CustomFieldsEntityTypeEnum)

Filter to Custom Field Definitions placed on this resource type. When omitted, definitions across all resource types are returned.

Enum: "RISK" "CONTROL" "ASSET" "PERSONNEL" "VENDOR" "FRAMEWORK_REQUIREMENTS"
isHidden
boolean

Filter by hidden state. When omitted, both hidden and non-hidden Custom Field Definitions are returned. When true, only hidden definitions are returned; when false, only non-hidden.

Example: isHidden=false
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

get/custom-field-definitions
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "customFieldId": 42,
      • "name": "Regulatory Owner",
      • "description": "Team accountable for the item",
      • "type": "OPTIONS",
      • "isRequired": true,
      • "isHidden": false,
      • "readOnly": false,
      • "entityTypes": [
        • "RISK"
        ],
      • "currencyCode": "USD",
      • "frameworkScope": {
        • "frameworkTags": [
          • "CUSTOM"
          ],
        • "frameworkIds": [
          • 0
          ]
        },
      • "options": [
        • {
          • "customFieldOptionId": 1,
          • "value": "Security & IT"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Create Custom Field Definition
Create a new Custom Field Definition. FORMULA fields cannot be created via the public API — they are computed by the platform and are always read-only. API-key authentication only — this endpoint does not support OAuth. Returns a 400 if the account has already reached its tenant-wide Custom Field placement limit.


🔒 Requires Custom Field Definitions: Create Custom Field Definitions permission.


💎 Requires your account have the Custom Fields and Formulas feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
Request Body schema: application/json
required
name
required
string  <= 191 characters NAME_FIELD_REGEX_VALIDATION
Name of the Custom Field Definition. Must be unique for this account.


 
description
string or null  <= 30000 characters 
Description of what this Custom Field is used for.


 
fieldType
required
string
Data type for this Custom Field. FORMULA fields cannot be created via the public API — they are computed by the platform.


 Enum: "TEXT" "NUMBER" "CURRENCY" "OPTIONS" "OPTIONS_NUMERIC" "LONG_TEXT" "URL"  
isHidden
required
boolean
 Default:  false
Whether the Custom Field is hidden.


 
isRequired
required
boolean
 Default:  false
Whether the Custom Field is required when creating a resource it is placed on.


 
Array of objects or null (CustomFieldDefinitionLocationRequestPublicV2Dto)   unique 
Where the Custom Field will appear.


 
Array of objects or null (CustomFieldDefinitionOptionRequestPublicV2Dto)   [ 2 .. 100 ] items  unique 
The selectable options for an OPTIONS field. Required when fieldType is OPTIONS.


 
Array of objects or null (CustomFieldDefinitionNumericOptionRequestPublicV2Dto)   [ 2 .. 100 ] items  unique 
The selectable numeric options for an OPTIONS_NUMERIC field. Required when fieldType is OPTIONS_NUMERIC.


 
object or null
Currency code. Required when fieldType is CURRENCY.


 
Responses 
201
Created


400
Malformed data and/or validation errors


401
Invalid Authorization


402
You must upgrade your plan to use this feature


403
You are not allowed to perform this action


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


post/custom-field-definitions
Request samples 
application/json
{
  • "name": "Regulatory Owner",
  • "description": "Team accountable for the item",
  • "fieldType": "TEXT",
  • "isHidden": false,
  • "isRequired": false,
  • "location": [
    • {
      • "entity": "RISK",
      • "section": "RISK_DETAILS",
      • "frameworkIds": [
        • 1,
        • 2,
        • 3
        ],
      • "frameworkTags": [
        • 1,
        • 2
        ]
      }
    ],
  • "options": [
    • {
      • "value": "BLUE",
      • "position": 1,
      • "isHidden": false
      },
    • {
      • "value": "BLUE",
      • "position": 1,
      • "isHidden": false
      }
    ],
  • "numericOptions": [
    • {
      • "value": 3,
      • "position": 1,
      • "isHidden": false
      },
    • {
      • "value": 3,
      • "position": 1,
      • "isHidden": false
      }
    ],
  • "currency": {
    • "code": "USD"
    }
}
Response samples 
application/json
{
  • "customFieldId": 42,
  • "name": "Regulatory Owner",
  • "description": "Team accountable for the item",
  • "type": "OPTIONS",
  • "isRequired": true,
  • "isHidden": false,
  • "readOnly": false,
  • "entityTypes": [
    • "RISK"
    ],
  • "currencyCode": "USD",
  • "frameworkScope": {
    • "frameworkTags": [
      • "CUSTOM"
      ],
    • "frameworkIds": [
      • 0
      ]
    },
  • "options": [
    • {
      • "customFieldOptionId": 1,
      • "value": "Security & IT"
      }
    ]
}
Get Custom Field Definition
Returns a single Custom Field Definition. The path parameter accepts either the numeric customFieldId or the field name prefixed with name: (e.g. name:Regulatory%20Owner). For durable integrations, store the numeric customFieldId from a previous response and address by ID — names may change if an admin renames the field. The name: form is a convenience for exploratory use and when you only know the name from the admin UI.


🔒 Requires Custom Field Definitions: Get Custom Field Definitions permission.


💎 Requires your account have the Custom Fields and Formulas feature. Contact your CSM for help upgrading.


Securitybearer 
Request 
path Parameters
required
number or string
An integer Custom Field Definition ID or the field name prefixed with name: (e.g. name:Regulatory Owner).


 
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


402
You must upgrade your plan to use this feature


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


422
Multiple Custom Field Definitions match the provided name. Use the numeric ID.


500
Internal server error


get/custom-field-definitions/{customFieldId}
Request samples 
Response samples 
application/json
{
  • "customFieldId": 42,
  • "name": "Regulatory Owner",
  • "description": "Team accountable for the item",
  • "type": "OPTIONS",
  • "isRequired": true,
  • "isHidden": false,
  • "readOnly": false,
  • "entityTypes": [
    • "RISK"
    ],
  • "currencyCode": "USD",
  • "frameworkScope": {
    • "frameworkTags": [
      • "CUSTOM"
      ],
    • "frameworkIds": [
      • 0
      ]
    },
  • "options": [
    • {
      • "customFieldOptionId": 1,
      • "value": "Security & IT"
      }
    ]
}