Disclosure API: Response - Update a Discloser's response

This article is for an API Partner wanting to make edits to a discloser’s response in the questionnaire-response Portal

Contents

• Summary

  • Guidelines

• PUT Request

  • URLs

  • Headers/Variables

  • Body

    • JSON Body (Generic Schema)

    • JSON Body (SINGLE_SELECT: Working example)

    • JSON Body (MULTI_SELECT: Working example)

    • New for 2026: Ability to unselect Options

    • JSON Body (NUMERIC: Working example)

    • JSON Body (DATE: Working example)

    • JSON Body (RICH_TEXT: Working example)

    • JSON Body (MATRIX: Working example)

    • JSON Body (GROUPED_OPTIONS: Working example)

  • Response

    • JSON Response Schema - Success

    • JSON Response Schema - Client Error

• Error Handling

  1. Invalid Subscription Key ID

  2. Invalid Organization ID

  3. Invalid questionId

  4. Previous Year Questions

  5. Invalid Status

  6. Non-Editable Response

  7. Invalid SINGLE_SELECT option

  8. Invalid Option - MULTI_SELECT

  9. Invalid Numerical Input

  10. Invalid/Incorrect Date

  11. Invalid/Incorrect Matrix Row ID

  12. Invalid/Incorrect GROUPED_OPTIONS value

  13. URL Error

  14. General Error

• POST/DELETE Requests

Summary

This article covers the PUT request, used to update a Discloser’s questionnaire-response.

Pre-requisites: 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 status is set to IN PROGRESS or AMENDMENTS (i.e., it is not possible to send a PUT request once a response is To check the status of a questionnaire call GET - Questionnaire metadata 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 isHidden status flag indicating whether the question is visible to the user in the portal. To check the isHidden property, call the GET - Retrieve a Discloser's Response endpoint).

4. To answer an expression (auto-calculation) question, an update must be sent based on the formulas provided by the GET - Expressions endpoint. The fields do 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 cannot be stored against the question.

8. Send a null value to reset:

   • A numeric or rich text question.

   • A date.

   • Single/multi select and/or grouped options questions.

PUT Request

The information provided below shows how to structure a request to update a Discloser’s questionnaire-response, for each question type. This shows each question type in isolation, however, it is expected that multiple question updates are sent together.

Note: All fieldnames throughout the API are formatted using camel casing.

Known limitation: Large batch updates

Requests that update a very large number of matrix cells in a single call (roughly 2,000 or more) currently fail with an error rather than being processed. This affects responses to matrix questions with many added rows.

Workaround: Split large updates into smaller batches, around 1,000 cells per request is a safe upper limit and submit them sequentially. Each batch is processed independently, so a failure in one batch does not roll back previously submitted batches.

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): A valid partner organization ID.

Body

Field table
 

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 property is used to determine if a value is currently relevant to a Discloser’s response. To check the isHidden property, call the GET - Retrieve a Discloser's Response endpoint.

1. "UNANSWERED"– The question has not yet 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 is marked as reviewed.

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

Note: All the statuses aside from ANSWERED and UNANSWERED only apply to top -level questions/do not apply to cells in matrix questions.

JSON Body (Generic Schema)

The example below shows a typical successful update. In practice, bulk updates should be sent to multiple questions simultaneously.
 

JSON Body (SINGLE_SELECT: Working example)

1. Validation on single select is based on "id" and not "name". However, the name must be present and not null.

Standard option:
 

2. The following shows how to configure the isOther value through the API. When done via the CDP portal, users must select the option “Other, please specify” and a description field is subsequently revealed to enable a custom text value to be added to the response.

Note: If the question is part of a matrix question, then the rowId needs to be included in the request.

“isOther” option (within a matrix question):
 

JSON Body (MULTI_SELECT: Working example)

Validation on multi select is based on "id" and not "name". However, the name field must be present and not null.