> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Data Subject's Data Elements

Use this API to create a new data subject or update an existing data subject. The data subject will be created or updated with the details provided in the request body.

> 🗒 Things to Know
> 
> - The data subject primary identifier cannot be updated. However, additional identifiers can be added, updated, or deleted:
>   - To add or update an additional identifier for a given data subject, set the `linked` parameter value to `true` and include a list of the additional identifiers within the `value` parameter.
>   - To remove an additional identifier from a given data subject, set the `linked` parameter value to `true` and leave the `value` parameter empty. Removed identifiers will remain associated with the data subject as data elements.
> - This API is not designed to be used in synchronous workflows and will not trigger integration events or reporting updates.

Below are templated examples of adding, editing, and deleting additional identifiers for the data subject.

```json Add
{
  "dataElements": [
    {
      "name": "ADDITIONAL_IDENTIFIER_TYPE", // For example: Email
      "linked": true, // When dealing with identifiers, set this value to true
      "value": ["EXISTING IDENTIFIER", "NEW_IDENTIFIER"] // Make sure to keep the existing identifier if you already have one for that type
    }
  ]
}
```
```json Edit
{
  "dataElements": [
    {
      "name": "ADDITIONAL_IDENTIFIER_TYPE", // For example: Email
      "linked": true, // When dealing with identifiers, set this value to true
      "value": ["EDITED IDENTIFIER"] // Make sure to keep the existing identifier if you already have one for that type
    }
  ]
}
```
```json Delete
{
  "dataElements": [
    {
      "name": "ADDITIONAL_IDENTIFIER_TYPE", // For example: Email
      "linked": true, // When dealing with identifiers, set this value to true
      "value": [] // Keep empty if you want to remove all additional identifiers that share the identifier type
    }
  ]
}
```

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Consent & Preferences - Universal Consent & Preference Management (OAS)",
    "version": "1.0",
    "contact": {
      "name": "OneTrust Support",
      "url": "https://my.onetrust.com/s/contactsupport"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "description": "The Universal Consent & Preference Management APIs are used to integrate external systems and streamline the flow of data with Universal Consent & Preference Management in the OneTrust Platform."
  },
  "servers": [
    {
      "url": "https://{hostname}",
      "variables": {
        "hostname": {
          "default": "hostname",
          "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com."
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Data Subjects",
      "description": "The Data Subjects APIs are used to manage individuals whose data is being processed.",
      "externalDocs": {
        "description": "OpenAPI 3.1.0 - Download Definition",
        "url": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
      },
      "x-displayName": "Data Subjects"
    }
  ],
  "paths": {
    "/api/consentmanager/v1/datasubjects/dataelements": {
      "post": {
        "operationId": "createOrUpdateDataSubjectUsingPOST",
        "summary": "Update Data Subject's Data Elements",
        "description": "Use this API to create a new data subject or update an existing data subject. The data subject will be created or updated with the details provided in the request body.\n\n> 🗒 Things to Know\n> \n> - The data subject primary identifier cannot be updated. However, additional identifiers can be added, updated, or deleted:\n>   - To add or update an additional identifier for a given data subject, set the `linked` parameter value to `true` and include a list of the additional identifiers within the `value` parameter.\n>   - To remove an additional identifier from a given data subject, set the `linked` parameter value to `true` and leave the `value` parameter empty. Removed identifiers will remain associated with the data subject as data elements.\n> - This API is not designed to be used in synchronous workflows and will not trigger integration events or reporting updates.\n\nBelow are templated examples of adding, editing, and deleting additional identifiers for the data subject.\n\n```json Add\n{\n  \"dataElements\": [\n    {\n      \"name\": \"ADDITIONAL_IDENTIFIER_TYPE\", // For example: Email\n      \"linked\": true, // When dealing with identifiers, set this value to true\n      \"value\": [\"EXISTING IDENTIFIER\", \"NEW_IDENTIFIER\"] // Make sure to keep the existing identifier if you already have one for that type\n    }\n  ]\n}\n```\n```json Edit\n{\n  \"dataElements\": [\n    {\n      \"name\": \"ADDITIONAL_IDENTIFIER_TYPE\", // For example: Email\n      \"linked\": true, // When dealing with identifiers, set this value to true\n      \"value\": [\"EDITED IDENTIFIER\"] // Make sure to keep the existing identifier if you already have one for that type\n    }\n  ]\n}\n```\n```json Delete\n{\n  \"dataElements\": [\n    {\n      \"name\": \"ADDITIONAL_IDENTIFIER_TYPE\", // For example: Email\n      \"linked\": true, // When dealing with identifiers, set this value to true\n      \"value\": [] // Keep empty if you want to remove all additional identifiers that share the identifier type\n    }\n  ]\n}\n```",
        "tags": [
          "Data Subjects"
        ],
        "x-onetrust": {
          "spec-label": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
        },
        "parameters": [
          {
            "name": "dataSubjectIdentifier",
            "in": "header",
            "description": "Unique identifier for the data subject. This is typically an email address or other unique identifier.",
            "required": true,
            "schema": {
              "type": "string",
              "example": "user@example.com",
              "maxLength": 255,
              "minLength": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "Contains a list of data elements with their values to be associated with the data subject.",
                "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectCreateDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK - Data elements successfully updated for the data subject.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectDetailDTO"
                }
              }
            }
          },
          "201": {
            "description": "Created - New data subject created successfully with the provided data elements.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectDetailDTO"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "429": {
            "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "description": "The number of seconds after which requests will be allowed again.",
                  "format": "int32"
                }
              },
              "ot-period": {
                "schema": {
                  "description": "The unit of time for which the rate limit applies",
                  "enum": [
                    "HOUR",
                    "MINUTE"
                  ]
                }
              },
              "ot-ratelimit-event-id": {
                "schema": {
                  "description": "The unique identifier for the rate-limiting event.",
                  "format": "uuid"
                }
              },
              "ot-request-made": {
                "schema": {
                  "description": "The number of requests made within the specified period.",
                  "format": "int32"
                }
              },
              "ot-requests-allowed": {
                "schema": {
                  "description": "The number of requests allowed within the specified period.",
                  "format": "int32"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": [
              "CONSENT"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectCreateDTO": {
        "type": "object",
        "properties": {
          "dataElements": {
            "description": "List containing the Data Subject's Data Elements",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementDTO"
            }
          },
          "identifierType": {
            "description": "The type of identifier used for the Data Subject",
            "type": "string",
            "example": "Email"
          },
          "language": {
            "description": "The preferred language code for the Data Subject",
            "type": "string",
            "example": "en-us"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementDTO": {
        "properties": {
          "name": {
            "description": "The name of the data element",
            "type": "string",
            "example": "Work Email"
          },
          "value": {
            "description": "The value of the data element",
            "type": "object",
            "example": "example@otprivacy.com",
            "maxLength": 750
          },
          "linked": {
            "description": "Indicates whether the data element can be used as an additional identifier",
            "type": "boolean",
            "example": true
          },
          "interactionDate": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "name"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_AdditionalIdInvalidScenariosDto": {
        "properties": {
          "name": {
            "type": "string"
          },
          "values": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectDetailDTO": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier for the Data Subject",
            "type": "string",
            "format": "uuid",
            "example": "633ba071-61b0-485f-81a0-a2245777b432"
          },
          "identifier": {
            "description": "The Data Subject's identifier value (e.g., email, phone number)",
            "type": "string",
            "example": "example@otprivacy.com"
          },
          "identifierType": {
            "description": "The type of identifier used for the Data Subject",
            "type": "string",
            "example": "Email"
          },
          "canBePrimary": {
            "description": "Indicates if the Data Subject can be used as a primary identifier for a group of related identifiers",
            "type": "boolean",
            "example": true
          },
          "elements": {
            "description": "List of data elements associated with the Data Subject",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementDTO"
            }
          },
          "messages": {
            "description": "List of validation or processing messages related to the Data Subject",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Invalid Data Element Name : Account Number"
            ]
          },
          "additionalIdMessages": {
            "description": "List of validation messages related to additional identifiers",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_AdditionalIdInvalidScenariosDto"
            }
          }
        },
        "required": [
          "identifier",
          "identifierType"
        ]
      }
    },
    "securitySchemes": {
      "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{hostname}/api/access/v1/oauth/token",
            "scopes": {
              "CONSENT": "Consent Scope gives the user access to read/write operations",
              "CONSENT_READ": "Consent Read Scope gives the user read-only access"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  },
  "x-onetrust": {
    "spec-label": "OpenAPI 3.1.0"
  }
}
````