This article is for an API Partner wanting to make edits to a discloser’s response in the questionnaire-response portal.
Summary
When interacting with a Discloser’s response data you can call two methods GET and PUT. This article covers the PUT request, which allows you to update an individual discloser’s questionnaire-response.
Prerequisites: Valid subscription key and organization UUID for the respective Disclosure API environment.
Guidelines
1. All questions that are part of the Discloser’s response can be retrieved and updated.
2. It will only be possible to PUT when the response workflow state is in a “IN PROGRESS” or “AMENDMENTS” state (e.g., it will not be possible to send a PUT request once a response has been submitted).
3. When a value is updated into a question which has been hidden by show/hide conditional logic, the value is stored until the response is submitted. Should the question become visible again (if the answer to a lead question changes), the previously hidden value would be included in the submission. Response data includes a status flag indicating whether the question is visible to the user in the portal.
4. To answer an expression (auto-calculation) question the API Partner must send the update to the question based on the formulas given via the “Expressions” endpoint. The fields will not auto-calculate when the dependent questions are updated.
5. Answers sent to an expression (auto-calculation) question will not be validated by the CDP portal. You must ensure the calculation is performed correctly before sending the value.
6. A GET request can be sent after a PUT request to verify the update to the data.
7. When updating a matrix question a rowId must be provided or the update will not be stored against the question.
8. To reset a numeric or rich text question, an empty string "" should be sent.
9. To reset a date question, send null.
10. Single/multi select and grouped options cannot be cleared. Users can only overwrite these answers.
11. File attachments cannot be removed via the API. The only way to do this is from the front-end portal on CDP's side.
PUT Request
Information on how to structure the requests to update a discloser’s questionnaire-response, for each question type. This shows each question type in isolation, but it is expected that you would send multiple questions updates together.
Note: all fieldnames throughout the API are formatted using camel casing.
URLs
Headers/Variables
subscription-key (header): For authorized user, the primary/secondary subscription key.
organisation-id (header): A valid partner organization ID is required to get tagging details of a specific organization.
Body
Field | Description | Data Type |
id | The ID of question to be updated | string |
rowId | For Matrix question type only: the ID of the row in which the question to be updated sits. Note: a rowID must be provided when updating a matrix question or the data will be lost. | string |
updateResponseInput | Additional info regarding the content and status update to be made:
“content”: the ID AND name for an option OR The answer-value to be updated
“status”: the answer status for the question to change to (see below). | array |
Field Table
Note: The “status” field controls how the question will be displayed in the portal and are checked as part of the submission process. You should ensure they are updated correctly with each change to an answer-value:
- “UNANSWERED” – The question has not yet been answered.
- “ANSWERED” – The question is answered or has been marked by the user as answered
- “SKIPPED” – The question is marked as skipped by the user. No content has been filled.
- “REVIEWED” – The question has been marked as reviewed by the submission lead.
- “CONDITIONAL” – The question is currently locked/hidden in the CDP Portal by conditional logic.
JSON Body (Generic Schema)
[{
"id": "string",
"rowId": "string",
"updateResponseInput": {
"content": {},
"status": "string"
}
}]
This (and the examples below) is a single question update schema for demonstration purposes, however in reality it is expected that you would be sending bulk updates to multiple questions at once.
JSON Body (SINGLE_SELECT: Working example)
Known Issue: As noted in the GET /questions endpoint some of the option names may contain whitespace that needs to be included for the update to be accepted.
Standard option:
"id": "20eb23ce-6316-43fa-8e7a-6eaee7d5b615",
"updateResponseInput": {
"content": {
"id": "68a11cd1-2c08-4cf8-9e42-8586fa9dd086",
"name": "Latin American Spanish",
"isOther": false
},
"status": "ANSWERED"
}
}]
Note: If the question is part of a matrix question, then the rowId needs to be included.
“isOther” option (within a matrix question):
[{
"id": "e8f912e9-9d87-4007-8c70-1cdfc1c5889e",
"rowId": "ba00926f-b1bf-47be-abee-3682304590f2",
"updateResponseInput": {
"content": [{
"id": "20d55649-ccb0-4e60-92e4-243c7aa23614",
"name": "Other, please specify",
"description": "CDP Test Other",
"isOther": true
}],
"status": "ANSWERED"
}
}]
JSON Body (MULTI_SELECT: Working example)
[{
"id": "ab565104-39b7-453c-a4a0-adc4b249c904",
"updateResponseInput": {
"content": [{
"id": "5f6d9d1e-8684-4b75-a6ac-9b738af73ef2",
"name": "Afghanistan",
"isOther": false
}, {
"id": "3802bb82-1161-4bd1-9f61-27aeec37c065",
"name": "Åland Islands",
"isOther": false
}
],
"status": "ANSWERED"
}
}]
Known Issue: As noted in the GET /questions endpoint some of the option names may contain whitespace that needs to be included for the update to be accepted.
JSON Body (NUMERIC: Working example)
[{
"id": "63379134-1ac4-4eb0-b237-522968486e95",
"updateResponseInput": {
"content": "100.12",
"status": "ANSWERED"
}
}
]
Note: The numeric value entered should not contain commas. And should match any criteria set out in the “validationRules”.
JSON Body (DATE: Working example)
Note: The Date Format must be in ISO-8601 format.
[{
"id": "48f3dc87-6c20-4188-818b-55e89c9507bc",
"updateResponseInput": {
"content": "2023-03-20T23:00:00.000Z",
"status": "ANSWERED"
}
}
]
JSON Body (RICH_TEXT: Working example)
Note: Rich text formatting cannot be inserted into rich text questions at column level in the current build. Any formatting entered will be taken as a literal string value.
[{
"id": "ab7d4318-95af-47a6-8099-4faec1461718",
"updateResponseInput": {
"content": "Hello, world!",
"status": "ANSWERED"
}
}
]
JSON Body (MATRIX: Working example)
[{
"id": "80bf9fe2-4d69-4f7d-8b87-3221fc0df3b1",
"updateResponseInput": {
"content": null,
"status": "PROGRESS"
}
}, {
"rowId": "175d6e79-6de8-4558-95a8-5cdbfc8eebef",
"id": "81f130b3-a4d5-4e43-a63a-c9c458708655",
"updateResponseInput": {
"content": "999.99",
"status": "ANSWERED"
}
}
]
Updates to matrix questions can be made to both the parent and the child/column question(s) at the same time as shown. You cannot add content to the parent question as this does not hold any answer-value data .
Note: If you update a matrix question value without adding a rowId then the update is lost, and no error is returned to flag this.
JSON Body (GROUPED_OPTIONS: Working example)
[{
"id": "6d72259c-74ae-46d7-a967-e382d9f6d052",
"updateResponseInput": {
"content": [{
"group": " 4ca9391d-8864-4f76-b7b2-41dd8a5310cf ",
"name": "France",
"options": [{
"id": "3389f9d1-750c-4fb3-9f11-c5d8ee9b5bc",
"name": "Loire",
"isOther": false
}
]
}
],
"status": "ANSWERED"
}
}
]
Known Issue: As noted in the GET /questions endpoint some of the option names may contain whitespace that needs to be included for the update to be accepted.
Response
JSON Response Schema – Success
The following message will be displayed on successful updating of the content.
{
"responseVersion": integer
}
JSON Response Schema – Client Error
The following message will be displayed on unsuccessful updating of the content.
Note: If any part of the update fails, then the whole update will be rejected and no changes would occur in the CDP Portal.
{
"message": "string",
"questionId": "string",
"responseContent": {},
"statusCode": 0,
"error": "string",
"minDate": "string",
"maxDate": "string",
"textLength": 0,
"textMaxLength": 0,
"maxDecimals": 0,
"minValue": 0,
"maxValue": 0,
"invalidOptions": {},
"dataTypeErrors": {}
}
As much as possible the error messages will direct you to where the issue was found in the provided PUT request body.
POST/DELETE Requests
POST requests are not implemented for this endpoint, as updates can only be made against an existing response.
DELETE requests are not implemented for this endpoint, preventing deletion of a discloser’s response data.
If you have not found the answer you were looking for, please contact your account manager who will be able to assist you further.