Data Classification API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 7 minutes to read

    • The Data Classification API provides endpoints to group data by type.

    With the Data Classification API, you can:
    • Assign data classifications to existing dictionary entries.
    • Look up the data classifications for specific dictionary entries.
    • Remove all data classifications associated with specific dictionary entries.
    • Retrieve a list of all data classifications available in the current domain.

    This API requires the Data Classification [com.glide.data_classification] plugin.

    For more information, see Data Classification.

    Data Classification - GET /data_classification/getAllDataClasses

    Returns a list of all data classifications available in the current domain.

    Requires the admin, data_classification_admin, or data_classification_auditor role.

    URL format

    Default URL: /api/now/data_classification/getAllDataClasses

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.

    Response body parameters (JSON or XML)

    Name Description
    result

    Result of the request. Returns the sys_id and name for each available data classification. If there are no data classifications, it returns an empty array.

    Data classifications can be organized into parent-child relationships. If there are parent data classifications, they are identified in the result.

    Data type: Array

    "result": [
  {
    "parent": {Object},
    "sys_id": "String",
    "name": "String"
  }
]
    result.parent Entry for a parent data classification.

    Data type: Object

    "parent": {
  "sys_id": "String",
  "name": "String"
}
    result.parent.sys_id Sys_id of the parent data classification from the Data Classification [data_classification] table.

    Data type: String
    result.parent.name Name of the parent data classification.

    Data type: String
    result.sys_id Sys_id of the data classification from the Data Classification [data_classification] table.

    Data type: String
    result.name Name of the data classification.

    Data type: String

    cURL request

    Retrieves a list of all the available data classifications.

    curl "https://instance.servicenow.com/api/now/data_classification/getAllDataClasses" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'
    {
  "result": [
    {
      "parent": {
        "sys_id": "a9670fc773fc1010ae8dd21efaf6a735",
        "name": "Confidential"
      },
      "sys_id": "348107b951d71010f877f3f178e7dd0d",
      "name": "Personally identifiable information"
    },
    {
      "sys_id": "a9670fc773fc1010ae8dd21efaf6a735",
      "name": "Confidential"
    },
    {
      "sys_id": "59b7070b73fc1010ae8dd21efaf6a764",
      "name": "Restricted"
    },
    {
      "sys_id": "11d60fc773fc1010ae8dd21efaf6a744",
      "name": "Internal"
    },
    {
      "sys_id": "f5b4cf4773fc1010ae8dd21efaf6a766",
      "name": "Public"
    }
  ]
}

    Data Classification - POST /data_classification/classify

    Assigns pre-defined or user-defined data classifications to existing dictionary entries.

    Requires the admin or data_classification_admin role.

    URL format

    Default URL: /api/now/data_classification/classify

    Supported request parameters

    Table 7. Path parameters
    Name Description
    None
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (XML or JSON)
    Name Description
    dictionary_entries Required. The sys_ids of the records you want to classify. The sys_ids are from the Dictionary [sys_dictionary] table. Entered as a comma-separated list enclosed in a string.

    Data type: String
    data_classes Required. The sys_ids of the data classifications you want to assign. The sys_ids are from the Data Classification [data_classification] table. Entered as a comma-separated list enclosed in a string.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Content-Type Data format of the request body. Supported types: application/json or application/xml.

    Default: application/json
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    result Message describing the result of the operation.

    Data type: String

    cURL request

    Assigns a data classification to a dictionary entry.

    curl "https://instance.servicenow.com/api/now/data_classification/classify" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"dictionary_entries\": \"445de0a6dba30300efc57416bf9619b0\",
    \"data_classes\": \"40edb1f51bbcec50b92a10a61a4bcb8a\"
}" \
--user 'username':'password'

    {
  "result": "Successfully stored the data classification configurations"
}

    Data Classification - POST /data_classification/clear

    Removes all data classifications for the specified dictionary entries.

    Requires the admin or data_classification_admin role.

    URL format

    Default URL: /api/now/data_classification/clear

    Supported request parameters

    Table 13. Path parameters
    Name Description
    None
    Table 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (XML or JSON)
    Name Description
    dictionary_entries Required. The sys_ids of the records you want to remove classifications from. The sys_ids are from the Dictionary [sys_dictionary] table. Entered as a comma-separated list enclosed in a string.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 16. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Content-Type Data format of the request body. Supported types: application/json or application/xml.

    Default: application/json
    Table 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    result Message describing the result of the operation.

    Data type: String

    cURL request

    Clears the data classifications for a dictionary entry.

    curl "https://instance.servicenow.com/api/now/data_classification/clear" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"dictionary_entries\": \"445de0a6dba30300efc57416bf9619b0\"
}" \
--user 'username':'password'

    {
  "result": "Classifications removed for the specified dictionary entries"
}

    Data Classification - POST /data_classification/getClassification

    Retrieves all data classifications for the specified dictionary entries.

    Requires the admin, data_classification_admin, or data_classification_auditor role.

    URL format

    Default URL: /api/now/data_classification/getClassification

    Supported request parameters

    Table 19. Path parameters
    Name Description
    None
    Table 20. Query parameters
    Name Description
    None
    Table 21. Request body parameters (XML or JSON)
    Name Description
    dictionary_entries Required. The sys_ids of the records you want to retrieve classifications for. The sys_ids are from the Dictionary [sys_dictionary] table. Entered as a comma-separated list enclosed in a string.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 22. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Content-Type Data format of the request body. Supported types: application/json or application/xml.

    Default: application/json
    Table 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 24. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    result

    Result of the request. Returns a JSON object containing each dictionary entry's sys_id with an array of its associated data classifications. If there are no associated data classifications, it returns a message describing the result of the operation.

    Data classifications can be organized into parent-child relationships. If there are parent data classifications, they are identified in the result.

    Data type: Object

    "result": {
  <sys_dictionary_sys_id>: [
    {
      "parent": {Object},
      "sys_id": "String",
      "name": "String"
    }
  ]
}
    result.name Name of the data classification.

    Data type: String
    result.parent Entry for a parent data classification.

    Data type: Object

    "parent": {
  "sys_id": "String",
  "name": "String"
}
    result.parent.name Name of the parent data classification.

    Data type: String
    result.parent.sys_id Sys_id of the parent data classification from the Data Classification [data_classification] table.

    Data type: String
    result.sys_id Sys_id of the data classification from the Data Classification [data_classification] table.

    Data type: String

    cURL request

    Get the data classifications associated with a specific dictionary entry.

    curl "https://instance.servicenow.com/api/now/data_classification/getClassification" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"dictionary_entries\": \"445de0a6dba30300efc57416bf9619b0\"
}" \
--user 'username':'password'

    {
  "result": {
    "445de0a6dba30300efc57416bf9619b0": [
      {
        "parent": {
          "sys_id": "a9670fc773fc1010ae8dd21efaf6a735",
          "name": "Confidential"
        },
        "sys_id": "348107b951d71010f877f3f178e7dd0d",
        "name": "Personally identifiable information"
      }
    ]
  }
}