Disclosure API: Technical Overview

This article is for an API Partner integrating with the Disclosure API to update individual responses for disclosing organizations. 

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 part of the ASP Programme in addition to being an API Partner then you may also receive a JSON 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). 

Naming Conventions 

• 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: "2025-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. 

Note: We are using a new sandbox environment for 2025 so please ensure you update the URL to include “asp” as above. 

Known Issue - Dev Portal: when viewing the API schema in Azure Dev Portal you will notice the incorrect addition of “swagger” in the URL path. This is wrong and the URLs as shown in this article are correct. 

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.