Views:

This article is for an API Partner wanting to retrieve partner organization response information.

Contents

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 “isHidden” 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

Sandbox: https://api.pre.cdpgreenstar.net/asp/response/response

Production: https://api.cdp.net/response/response

Headers/Variables

subscription-key (header): For authorized user, the subscription key.

organization-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

Data Type

id

The ID of the response record 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.

array

discloserId

The internal CDP ID of the user that last edited the answer-value in the CDP Portal.

array

partnerId

The internal CDP ID of the API Partner that updated the response via the API.

array

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. The “isHidden” field is used to determine if a value is currently relevant to a Discloser's response.

  1. "UNANSWERED"– The question has not been answered.

  2. "ANSWERED"– The question is answered or has been marked by the user as answered.

  3. "SKIPPED"– The question is marked as skipped by the user. No content has been filled.

  4. "REVIEWED"– The question has been marked as reviewed by the Submission Lead.

  5. "PROGRESS" – The question is currently in the process of being answered (matrix questions only). 

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 last 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 answer-value 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

The ID that is generated if new rows are created via “Add row” button in the Portal or through API endpoint.

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
 

[{

...
     "attachemnts": {

       "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": 11111,
              "fileName":  “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.

Keywords: Disclosure API, API, ASP, API Partner
Comments (0)
Add a comment