This article is for an API Partner wanting to retrieve partner organization response information.
Summary
When interacting with a Discloser’s response data you can call two methods GET and PUT. This article covers the GET request, which allows you to retrieve the existing answer-values in an individual response. A GET request can be sent after a PUT request to verify the update to the data.
Pre-requisites: Valid subscription key and organization UUID for the respective Disclosure API environment.
Note - Data Sync: To ensure you are seeing the latest answer-values within a discloser’s questionnaire-response then this data should be refreshed when updates are made to the response, either via the API or within the portal directly.
Note - Hidden Questions: When a value is updated into a question which has been hidden by show/hide conditional logic, the value is stored regardless. Should the question become visible again (if the answer to a lead question changes), the previously hidden value would be included in the submission. You can see this using the “status” field.
Note – Different States: It is possible to GET when the response workflow is in an “In Progress”, “Submitted” or “Amendments” state.
GET Request
The GET request details how to send the request to the response/response endpoint and the response that is returned when a successful request is sent.
URLs
Production: https://api-prd.cdpgreenstar.net/response/response
Headers/Variables
subscription-key (header): For authorized user, the primary/secondary subscription key.
organisation-id (header): Enter the UUID for the organization’s response.
Body
NULL
Response
Top Level: Response (n)
Answer-value data for the specified organizations response.
Field Table
Field | Description | Format |
id | The ID of the response object within the entire response. This is unique to each organizations response. | integer |
content | The value of the response answer-value field. Note: use JSON.parse to clean string | string |
status | The status of the question-answer. See below. | string |
setAnsweredManually | Indicates if the status has been changed manually to “ANSWERED” in the portal by the user. | boolean |
questionId | The ID of the question the answer value refers to | string |
organizationId | The UUID of the organization the answer belongs to | string |
discloserId | The internal CDP ID of the user that last edited the answer-value in the CDP Portal. | string |
partnerId | The internal CDP ID of the API Partner that updated the response via the API. | string |
createdOn | Timestamp of when the answer-value was initially created | string |
updatedOn | Timestamp of when the answer-value was most recently updated | string |
rowId | For Matrix question type only: the ID of the row the answer-value belongs too | string |
responseVersionId | The ID of response version. |
|
row | For Matrix question type only: Additional information of a row in a matrix question. | array |
attachments | For Attachment question type only: additional information about the attached file: | array |
responseVersion | Response version to the question. | array |
Note: The “status” field is the current state of the question in the portal. These are for display purposes only; the discloser should ensure their response is filled out correctly prior to final submission.
- “UNANSWERED” – The question has not 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.
Known Issue - Update Source: The “source” of an answer-value update is not currently shared via the API. As such, you cannot tell if an answer-value was updated by a user in the portal, an Excel import or via the API.
Schema
[
{
"id": integer,
"content": "string",
"status": "string",
"setAnsweredManually": boolean,
"questionId": "string",
"organizationId": "string",
"discloserId": "string",
"partnerId": "string",
"createdOn": "string",
"updatedOn": "string",
"rowId": "string",
"responseVersionId": "string",
"row": [{…}],
"attachments": [{…}],
"responseVersion": [{…}]
}
]
Second Level: Rows (n+1)
Additional information about the row and matrix question that the expression belongs to, if applicable.
Field Table
Field | Description | Data Type |
id | The ID for the row within the matrix question. Pre-set row IDs are shared across all organizations and endpoints; newly created row IDs are unique to that specific questionnaire-response. | string |
refId | The permanent ID for the row within the matrix question. | string |
complexQuestionId | The ID of the parent matrix question | string |
instanceId | Not in use | string |
title | The name of the row | string |
order | The position of the row within the matrix question | integer |
Schema
[{
…
"row": {
"id": "string",
"refId": null,
"complexQuestionId": "string",
"instanceId": null,
"title": "string",
"order": integer
}
…
}]
Second Level: Attachments (n+1)
Attachment information added as part of the response to the question.
Note: The attachment files themselves cannot be retrieved via the API.
Field Table
Field | Description | Data Type |
id | The ID for the row within the matrix question. Pre-set row IDs are shared across all organizations and endpoints, newly created row IDs are unique to that specific questionnaire-response. | string |
fileName | The name of the attached file | string |
fileSize | The size of the attached file | integer |
fileType | Type of file attached | string |
fileStatus | The status of the file | string |
Schema
[{
…
"attachments": [{
"id": integer,
"fileName": "string",
"fileSize": integer,
"fileType": "string",
"fileStatus": "string"
}]
…
}]
Second Level: Response Version (n+1)
Response version to the question.
Field Table
Field | Description | Data Type |
version | The version number of the response to the specific question | string |
Schema
[{
…
"responseVersion": {
"version": "string"
}
…
}]
JSON Response Example
Below is an example API response while calling the GET method for this endpoint. The data retrieved is a part of the response to the questionnaire, currently held for that organization.
[
{
"id": 1234567,
"content": "null",
"status": "ANSWERED",
"setAnsweredManually": false,
"questionId": "14b2db4c-c9ef-4495-b020-7a8f436ae0ba",
"organizationId": "ldja212-121f-ds12-890a-000d4g21gl28",
"discloserId": "23df3456-2130-2g31-7a6h-3255450ac245",
"partnerId": null,
"createdOn": "2024-09-25T15:52:17.612Z",
"updatedOn": "2024-09-30T19:43:50.863Z",
"rowId": null,
"responseVersionId": "e1htf1f8-ra5h-4236-t0fd-4f3264ff7gy1",
"row": {
"id": "0e13121a-a696-221f-7065-c79c7ca542aa",
"refId": null,
"complexQuestionId": "9aa87751-7692-4a54-a00d-9c6c98fdea7a",
"instanceId": null,
"title": "Row 1",
"order": 1
}
"attachments": [{
"id": 11111,
"fileName": "CDP Admin.pdf",
"fileSize": 111111,
"fileType": "application/pdf",
"fileStatus": "uploaded"
}],
"responseVersion": {
"version": "1.0"
}
}
]
POST/PUT Requests
POST and PUT are implemented for this endpoint, these are covered in articles:
If you have not found the answer you were looking for, please contact your account manager who will be able to assist you further.