Work with Custom Fields

1. General

Custom Fields support is integrated with existing administrative (CRUD) API endpoints: GET, POST, PUT, and DELETE methods rather than implemented in separate, dedicated custom field endpoints.

For example, to set control custom field values for an existing control, use:

Copy

Copied

PUT https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls

Similarly to retrieve control custom field values for an existing control, use:

Copy

Copied

GET https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls/{controlId}

2. Assets

2.1 List Assets

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/assets?expand[]=customFields

Reference: List Assets API

2.2 Get Asset

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/assets/{assetId}?expand[]=customFields

Reference: Get Asset API

2.3 Update Asset

When updating an asset, custom fields may also be included or only be included as a part of the request payload.

Copy

Copied

PUT https://public-api.drata.com/public/v2/assets/{assetId}

Request Payload:

Copy

Copied

{
  "description": "MacBook Pro 16-inch with 14-Core CPU 32-Core GPU 36GB Unified Memory 1TB SSD Storage",
  "notes": "This is a MacBook Pro",
  "customFields": [
    {
      "name": "Stakeholders",
      "value": "Security & IT"
    },
    {
      "name": "Amount",
      "value": 56.89
    }
  ]
}

Reference: Update Asset API

2.4 Create Asset

When creating an asset, custom fields may also be included as a part of the request payload.

Note: If any required custom fields exist, they must be passed as a part of the required payload, otherwise, a 400 error will be returned.

Copy

Copied

POST https://public-api.drata.com/public/v2/assets

Request Payload:

Copy

Copied

{
  "name": "MacBook Pro 16-inch",
  "description": "MacBook Pro 16-inch with 14-Core CPU 32-Core GPU 36GB Unified Memory 1TB SSD Storage",
  "notes": "This is a MacBook Pro",
  "assetClassTypes": ["HARDWARE", "PERSONNEL"],
  "assetType": "PHYSICAL",
  "ownerId": 1,
  "customFields": [
    {
      "name": "Stakeholders",
      "value": "Customer"
    },
    {
      "name": "Amount",
      "value": 12.34
    }
  ]
}

Reference: Create Asset API

3. Controls

3.1 List Controls

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls?expand[]=customFields

Reference: List Controls API

3.2 Get Control

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls/{controlId}?expand[]=customFields

Reference: Get Control API

3.3 Modify Control

When updating a control, custom fields may also be included or only be included as a part of the request payload.

Copy

Copied

PUT https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls/{controlId}

Request Payload:

Copy

Copied

{
  "name": "Updated quarterly User Access Reviews",
  "description": "Updated access to critical systems is reviewed on a quarterly basis to ensure that only authorized users retain access.",
  "customFields": [
    {
      "name": "Stakeholders",
      "value": "Security & IT"
    },
    {
      "name": "Amount",
      "value": 56.89
    }
  ]
}

Reference: Modify Control API

3.4 Create Control

When creating a control, custom fields may also be included as a part of the request payload.

Note: If any required custom fields exist, they must be passed as a part of the required payload, otherwise, a 400 error will be returned.

Copy

Copied

POST https://public-api.drata.com/public/v2/workspaces/{workspaceId}/controls

Request Payload:

Copy

Copied

{
  "name": "Quarterly User Access Reviews",
  "description": "Access to critical systems is reviewed on a quarterly basis to ensure that only authorized users retain access.",
  "question": "A very good question",
  "code": "DRA-69",
  "activity": "On a quarterly schedule, generate access reports from identity providers.",
  "customFields": [
    {
      "name": "Stakeholders",
      "value": "Security & IT"
    },
    {
      "name": "Amount",
      "value": 56.89
    }
  ]
}

4. Personnel

4.1 List Personnel

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/personnel?expand[]=customFields

Reference: List Personnel API

4.2 Get Personnel

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/personnel/{personnelId}?expand[]=customFields

Reference: Get Personnel API

4.3 Update Personnel

When updating a personnel record, custom fields may also be included or only be included as a part of the request payload.

Copy

Copied

PUT https://public-api.drata.com/public/v2/personnel/{personnelId}

Request Payload:

Copy

Copied

{
  "startedAt": "2020-07-06",
  "separatedAt": "2020-07-06",
  "employmentStatus": "CURRENT_CONTRACTOR",
  "notHumanReason": "This is not a real personnel, but a placeholder for anyone in charge of X",
  "customFields": [
    {
      "name": "Stakeholders",
      "value": "Security & IT"
    },
    {
      "name": "Amount",
      "value": 56.89
    }
  ]
}

Reference: Update Personnel API

5. Vendors

5.1 List Vendors

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/vendors?expand[]=customFields

Reference: List Vendors API

5.2 Get Vendor

By default, custom field values are not returned in the response. By including the query parameter expand[]=customFields, custom fields are included in the response.

Copy

Copied

GET https://public-api.drata.com/public/v2/vendors/{vendorId}?expand[]=customFields

Reference: Get Vendor API

5.3 Update Vendor

When updating a vendor, custom fields may also be included or only be included as a part of the request payload.

Copy

Copied

PUT https://public-api.drata.com/public/v2/vendors/{vendorId}

Request Payload:

Copy

Copied

{
  "name": "Acme Vendor",
  "hasPii": true,
  "customFields": [
    {
      "id": 1,
      "name": "Compliance Status",
      "value": "Security & IT"
    }
  ]
}

Reference: Update Vendor API

5.4 Create Vendor

When creating a vendor, custom fields may also be included as a part of the request payload.

Note: If any required custom fields exist, they must be passed as a part of the required payload, otherwise, a 400 error will be returned.

Copy

Copied

POST https://public-api.drata.com/public/v2/vendors

Request Payload:

Copy

Copied

{
  "name": "Acme Vendor",
  "hasPii": true,
  "passwordMfaEnabled": true,
  "customFields": [
    {
      "id": 1,
      "name": "Compliance Status",
      "value": "Security & IT"
    }
  ]
}

Reference: Create Vendor API