Submit Data Change Request

Submit a Data Change Request (DCR) to one or more fields on an existing Investigator or Institution record controlled by OpenData Clinical. Learn more about Data Change Requests in Vault Help.

You can submit up to 10 Data Change Requests in one API call. In your request, you must provide the source_verified query parameter to confirm whether the submitted data originates from a third-party data provider.

POST/api/{version}/app/clinical/opendata/{object}/data_change_request

Headers

Name	Description
`Content-Type`	`application/json`
`Accept`	`application/json` (default)

URI Path Parameters

Name	Description
`{object}`	The name of the object to submit the Data Change Request. For example, `person__sys`.

Query Parameters

Name	Description
`source_verified`	To confirm that the submitted data does not originate from a third-party data provider, you must include a query parameter `source_verified=true`. Vault then validates the compliance check and successfully generates a DCR. If omitted, null, or `source_verified=false`, the operation fails and Vault does not create the DCR.

Body Parameters

In the body of the request, include a JSON input with the following fields for each Data Change Request:

Name	Description
`id` conditional	If you are requesting to update values on an existing record, include the ID of the record to submit the Data Change Request. If you are requesting to create a new record, omit this parameter.
`notes` required	A String field to provide the rationale or reasoning for this Data Change Request. This appears in the Notes field in the Vault UI. Cannot be null.
`data` required	A JSON object with the fields to update or create on the record, with their new values. Fields should use their API name format, for example, `first_name__sys`. When entering new values for picklist fields, use the name of the picklist value rather than the label as the new value for the picklist field. While the requested field names to populate are validated, the proposed values for requested fields are not validated, meaning the DCR may be sent with invalid proposed field values.

Request: Update Existing Investigators

curl --location 'https://myvault.veevavault.com/api/v26.3/app/clinical/opendata/person__sys/data_change_request?source_verified=true' \
--header 'Accept: ' \
--header 'Authorization: {AUTH_VALUE}' \
--data-raw '[
[ 
   {
        "id": "V0B000000003005",
        "notes": "DCR for legal name change",
        "data": { 
                "first_name__sys": "Megan",
                "last_name__sys": "Smith"
                }
    },
    {
        "id": "V0B000000003045",
        "notes": "DCR for legal name change",
        "data": { 
                "first_name__sys": "Kristin",
                "last_name__sys": "Smith"
                }
    }
]'

Response: Update Existing Investigators

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "source_verified": true,
   "data": [
       {
           "target_id": "V0B000000003005",
           "id": "VBH000000004001"
       },
       {
           "target_id": "V0B000000003045",
           "id": "VBH000000004002"
       }
   ]
}

Request: Create New Investigators

curl --location 'https://myvault.veevavault.com/api/v26.3/app/clinical/opendata/person__sys/data_change_request?source_verified=true' \
--header 'Accept: ' \
--header 'Authorization: {AUTH_VALUE}' \
--data-raw '[
    {
        "notes": "Request for Investigator Megan",
        "data": { 
                "first_name__sys": "Megan",
                "last_name__sys": "Smith"
                }
    },
    {
        "notes": "Request for Investigator Kristin",
        "data": { 
                "first_name__sys": "Kristin",
                "last_name__sys": "Smith"
                }
    }
]'

Response: Create New Investigators

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "source_verified": true,
    "data": [
        {
            "target_id": null,
            "id": "VBH000000003003"
        },
        {
            "target_id": null,
            "id": "VBH000000003004"
        }
    ]
}

Request: Source Not Verified

curl --location 'https://myvault.veevavault.com/api/v26.3/app/clinical/opendata/person__sys/data_change_request?source_verified=false' \
--header 'Accept: ' \
--header 'Authorization: {AUTH_VALUE}' \
--data-raw '[
    {
        "notes": "Request for Investigator Megan",
        "data": { 
                "first_name__sys": "Megan",
                "last_name__sys": "Smith"
                }
    },
    {
        "notes": "Request for Investigator Kristin",
        "data": { 
                "first_name__sys": "Kristin",
                "last_name__sys": "Smith"
                }
    }
]'

Response: Source Not Verified

{
   "responseStatus": "FAILURE", 
   "errors": [ 
{ 
    "type": "OPERATION_NOT_ALLOWED",
    "message": "Cannot submit data change requests: the data source is not verified because source_verified is set to false, null, or missing." 
}
    ]
}

Response Details

When requesting an update to an existing record, on SUCCESS the response contains the target_id of the record where the DCR was submitted, and the id of the new Data Change Request record.

When requesting to create a new record, on SUCCESS the response contains the id of the new Data Change Request record. The returnedtarget_id is null, as there is no existing record.

Partial success is not allowed, meaning either all records succeed or all records fail. On FAILURE, Vault returns an error message for the first error encountered.

Requesting to update values on an existing record or create a new record requires source verification (source_verified=true). On FAILURE, Vault returns an error message for the entire operation.