This article is for an API Partner integrating with the Disclosure API to update individual responses for disclosing organizations.
Contents
API Overview
Before you begin working on your integration with the Disclosure API it is important that you understand the structure of the CDP platform and the part into which you connect via the API:
As shown in the diagram above, the Disclosure API connects to the CDP questionnaire-response portal. The CDP questionnaire-response portal pulls together questionnaire data and organizational data, creating a single questionnaire-response instance record for each organization that has completed the onboarding for the given disclosure cycle.
The CDP authoring portal is a separate component of the platform which is where each cycle’s questionnaire is developed and finalized.
Referring to the API Definition included in the Introduction Article, you can see that this means everything that is returned by the Disclosure API is specific to a single organization and it is not possible to extract a complete list of all the questions in a single API request.
Note: if you are an ASP partner then you may also receive a JSON [VH5.1][CM5.2][VH5.3]file containing the entire questionnaire structure, questions, logic and expressions. This file is generated within the “CDP Authoring Portal” shown in the diagram above, and as such should not be used as part of the Disclosure API integration work. The format of these JSONs are not the same as those provided by the API response service and some key fields are not included which will make it impossible for you to re-create the entire questionnaire experience.
API Fundamentals
The API follows the RESTful API standard
Requests are single updates (atomic transactions)
PUT requests must be idempotent
Questionnaire-Response Versioning
When connecting to a Discloser’s questionnaire-response, you will only be able to connect to the latest version of their response, this is the case for all endpoints other than/organizations/partners.
This means that once a response has been submitted in the CDP portal you can no longer edit that version of their response. If the Discloser then chooses to edit their response, a new version is created, and you will be able to update it again via the API again.
It is only possible to update a response when the response is in a “IN_PROGRESS” or “AMENDMENTS” state (e.g., it will not be possible to send a PUT request once the discloser’s response has been submitted).
Questionnaire-Response Versioning
Attributes will be in camel case:
The first word is in lower case, and all subsequent words start with an upper case. Usually upper case “words”, such as initials, should not all be in capitals. (e.g. CdpDetails, not CDPDetails, and userId not userID).
Resources will be plural nouns
Error messaging is implemented across all endpoints to give clear instructions when an error is found in a request.
Tag Matching
The CDP Disclosure Portal includes the concept of “tag matching” to control the content which is shown to a specific organization when they access their questionnaire response.
Tag matching works by comparing “tags” assigned to the active organization and the tags assigned to questions, rows, columns and options in the CDP questionnaires. If question is tagged to a sector/theme/project/pathway/organization type/commodity then only organizations with the same tags will see these questions. This reduces the required number of individual logic rules.
Timestamp Formatting
ISO-8601 is used for any date-time fields returned in the Disclosure API. We do not ask for time values in our current questionnaires, so when updating a response all date-time values will be shown as date-only in the disclosure portal. Format: "2026-03-20T00:00:00.000Z"
Known Issue - Deadlines: Any CDP deadlines you wish to reflect in your platform should be taken from the publicly communicated deadlines on the CDP website, these will always use the IDLW time zone. The deadlines returned via the API, in particular the time component, will not be accurate.
Known Issue - Time zones: When updating a date value you will need to use the ISO-8601 format as above. However, when viewing those date answers in the CDP Portal a time zone offset will be applied between UTC and the user’s location. This can cause the date value to change.
Endpoints
Below are the set of endpoints that could be accessed as part of the Disclosure API. These endpoints are shared between the Sandbox & Production environments..
Sandbox: https://api-pre.cdpgreenstar.net/asp/response/
Production: https://api.cdp.net/response/
For example, the full URL path for the Questionnaire Metadata endpoint in the sandbox is: https://api-pre.cdpgreenstar.net/asp/response/questionnaire/metadata
If you have not found the answer you were looking for, please contact your Account Manager who will be able to assist you further.