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"
    }
}
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"
      }
    ]
}