This article is for an API Partner integrating with the Disclosure API to update individual responses for disclosing organizations.
Summary
Returns information on the relevant sections, questions, rows and options within a questionnaire for the specified organization.
Prerequisites: Valid subscription key and organization UUID of an associated disclosing organization, for the respective Disclosure API environment.
Note - Tag Matching: only the question data for a single organization can be extracted at one time, as such it is not possible to extract ALL questions in a single questionnaire at once. See “API Overview” section above for detail on “Tag Matching” which controls which questions are returned in question list response.
Note - Dynamic Loading: As mentioned, it is not possible to pull an “entire” CDP questionnaire via the Disclosure API. This is because the questionnaires contain various pathways, which cannot all be selected by a single organization. As such, we recommend you DO NOT create a “master” copy of the questionnaire and instead work to ensure dynamic loading of each user’s question lists as needed.
GET Request
Details how to send the request to the /questions endpoint and the response that is returned when a successful request is sent.
Note - Data Sync: To ensure that you have an accurate list of each discloser’s questions, it is recommended that you allow your users to sync their question data whenever changes are made by the user in the CDP Portal. Changes made during the questionnaire setup process or due to new requests, will often require the question data be refreshed.
URLs
Headers/Variables
subscription-key (header): For authorized user, the primary/secondary subscription key.
organization-id (header): The UUID for the organization you are requesting the question list for response.
Body
NULL
Response
Note: all fieldnames throughout the API are formatted using camel casing.
Top Level: Questionnaire Details (n)
Contains high-level information about the questionnaire the specified organization is associated to.
Field Table
Field | Description | Data Type |
id | The UUID for the questionnaire applicable to the requested organization. This ID is shared across all organizations and endpoints. | string |
name | The name for the questionnaire applicable to the requested organization. Note: For API Partners interacting with the corporate questionnaire, “CORPORATE” will be returned here for both the “Full” & “SME” versions of the questionnaire as these are different pathways within the same overall questionnaire. | string |
type | The organization type the questionnaire is associated too. | string |
scoringDeadline | The scoring deadline for the questionnaire in which organizations need to have submitted their response to receive a score. Note: timestamps and time zone can be ignored here as CDP deadline always refer to the IDLW time zone. | string |
version | The current version of the questionnaire that has been published into the CDP questionnaire-response portal. | string |
sections | Array list of sections within the relevant questionnaire. | array |
endDate | The relevant questionnaire close date after which questionnaire-response instances will not be accessible via the API. | string |
Schema
{
"id": "string",
"name": "string",
"type": "string",
"scoringDeadline": "string",
"version": "string",
"sections": [{ ... }],
"endDate": "string"
}
Second Level: Section Details (n+1)
Returns information about the sections of the questionnaire associated with the specified organization.
Field Table
Field | Description | Data Type |
id | The ID for the section within the questionnaire. This ID is shared across all organizations. | string |
title | The name of the section. | string |
code | The value of the section number | string |
description | The description provided for the section. Note: not used in current questionnaires | string |
type | The section type: “ INFORMATION_BLOCK” or “QUESTION_SECTION” | string |
order | Position of the section within the questionnaire (starting at index 0). | integer |
questions | Array list of questions within the relevant section. | array |
infoBlocks | List of information blocks which contain additional information/notes about a section. | array |
Schema
{
...
"sections": [{
"id": "string",
"title": "string",
"code": "string",
description": "string",
"type": "string",
"order": integer,
"questions": [{...}],
"infoBlocks": [...}]
}]
...
}
Third Level: Question (n+2)
A question list of all the questions relevant to the specified organization’s disclosure.
Field Table
Field | Description | Data Type |
id | The ID for the current version of the question within the questionnaire. This is shared across all organizations and endpoints. | string |
refId | The permanent ID of the question within the questionnaire. This is shared across all organizations and endpoints. | string |
blankOptions | Not in use | integer |
type | The question type for the given question: [“SINGLE_SELECT”, ”MULTI_SELECT”, ”NUMERIC”, ”DATE”, ”RICH_TEXT”, ”ATTACHMENT”, ”MATRIX”, ”GROUPED_OPTIONS”] | string |
isDynamic | For Matrix question type only: fixed row or dynamic matrix type. If this is ‘false’ then “isPrepop” will also be false. Dynamic matrix questions can have zero, one or many preset rows. | boolean |
isPrepop | For Matrix question type only: indicates if rows in matrix question are pre-specified for the user. If this is ‘true’ then there will always be at least a single row preset in the questionnaire structure and “isDynamic” will also be true. Has implications to add-row endpoint. | boolean |
allowCopyForward | Indicates if copy forward (taking answers from users previous cycle response) is enabled on the question. | boolean |
variant | An additional control of how a question is configured which should be consider alongside “type”. See below note. | string |
validationRules | Lists out the validation rules that have been applied to the question. e.g. min/max date, character limits, numeric range, decimal points. | string |
isMandatory | Indicates if the question is mandatory for submission. | boolean |
order | The position of the question within the section. | integer |
code | The reference for a questions position in the questionnaire (e.g. "1.24.2.7"). Note: matrix columns are listed as a decimal value under the parent question. This can lead to the same “code” appearing more than once. | string |
text | The main question text. | string |
simpleHelpText | Help text that appears next to the question text in the CDP Portal. | string |
popupHelpText | Help text that appears when the user hovers over the question title in the CDP Portal. | string |
sectionId | The section ID the question is within. | string |
groupId | Not in use at question level | string |
parentQuestionId | For Matrix question type only: the ID of the matrix question in which the child question sits. | string |
requestingAuthoritiesEnabled | Indicates if the requesting authorities are returned in the portal as part of the options list. Note: the option list will not be populated via the API. | boolean |
rowTitle | Not in use | string |
questionTags | List of tags that have been applied at question level to the given question. | array |
rows | For Matrix question type only: list of rows within the matrix question. Note: if empty then user can add additional rows. | array |
columns | For Matrix question type only: list of columns within the matrix question. | array |
tags | List of tags that have been applied at question level to the given question. | array |
options | For single and multi-select questions only: a list of available options for the question. | array |
optionGroups | For grouped questions: a list of available groups for the question. | array |
Note - Variants: The different options for “variant” depend on the question type:
- Grouped Options - controls what a user can select
- "SINGLE_GROUP_SINGLE_SELECT" - only a single option in a single group can be selected.
- "SINGLE_GROUP_MULTI_SELECT" - multiple options can be selected within a single group.
- "MULTI_GROUP_MULTI_SELECT" - multiple options can be selected across multiple groups.
- Matrix - the formatting of how matrix questions are displayed in the CDP portal.
- “TABLE” - in table view format
- “TAB” - in a tabbed view layout (not currently used)
- Numeric - formatting of numerical values in the CDP portal.
- “CURRENCY” - treated as a currency value
- ”YEAR” - can only be a 4-integer whole number
- ”DEFAULT” - any other number controlled by the validation rules
Schema
{
...
"questions": [{
"id": "string",
"refId": "string",
"blankOptions": integer,
“type": "string",
"isDynamic": boolean,
"isPrepop": boolean,
"allowCopyForward": boolean,
"variant": "string",
"validationRules": "string",
"isMandatory": boolean,
"order": integer,
"code": "string",
"text": "string",
"simpleHelpText": "string",
"popupHelpText": "string",
"sectionId": "string",
"groupId": null,
"parentQuestionId": "string",
"requestingAuthoritiesEnabled": boolean,
"rowTitle": "string",
"questionTags": [{...}],
"rows": [{...}],
"columns": [{...}],
"tags": [...}],
"options": [{...}],
"optionGroups": [...}]
}]
...
}
Fourth Level: Options (n+3)
An options list of all the options relevant to the specified organizations discloser.
Known Issue - Whitespace: When retrieving the option names from the JSON response, you will notice that some of the names contain a single space character at the end of the string. This whitespace must be maintained to allow the name to be returned within a PUT /response request, if the whitespace is removed then the update will be rejected as being an invalid option.
Field Table
Field | Description | Data Type |
id | The ID for the option within the given question. This is shared across all organizations and endpoints. | string |
name | The text value of the option name. Note: known issue with whitespace, see above. | string |
isOther | Indicates if the option is the “Other” option. | boolean |
refId | The permanent ID for the option within the given question. This is shared across all organizations and endpoints. | string |
questions | List of questions that the option is used by. | array |
optionTags | Not in use at option level | array |
tags | Not in use at option level | array |
Note - Ordering: In the current version of the API the ordering of the options is not shared. As such, you will not be able to recreate the lists in the exact order as they might appear in the CDP Portal. It is recommended that you sort them alphabetically or however you think best.
Known Issue - Requesting Members: Single or multi-select questions where the “requestingAuthoritiesEnabled” field is set to true indicate that the list of requesting members (usually Supply Chain members) for the discloser are shown in the options list. However, due to a limitation of the API these are not returned, and you will see a blank options list. In these cases, the disclosers will need to answer the questions in the CDP Portal directly.
Schema
{
...
"options": [{
"id": "string",
"name": "string",
"isOther": boolean,
“refId ": "string",
"questions": [{...}],
"optionTags": [{...}],
"tags": [{...}]
}]
...
}
Fourth Level: Option Groups (n+3) [Grouped Questions only]
This section is only relevant for Grouped Options type questions: An options list of all the options within the option group structure relevant to the specified organizations discloser.
Field Table
Field | Description | Data Type |
id | The ID for the group within the grouped question. This is a shared ID across all organizations and endpoints. | string |
name | The text value of the group name | string |
order | The position of the option group within the grouped option list. Numbers will be ascending values within a single option list. | integer |
refId | The permanent ID for the group within the grouped question. | string |
questions | List of questions that the option group is used by. | array |
options | A list of available options within each option group. | array |
Note - Ordering: In the current version of the API the ordering of the specific options is not shared. As such, you will not be able to recreate the lists in the exact order as they might appear in the CDP Portal. It is recommended that you sort them alphabetically or however you think best.
Schema
{
...
"options": [{
"id": "string",
"name": "string",
"order": integer,
“refId ": "string",
"questions": [{...}],
"options": [{...}]
}]
...
}
Fourth Level: Tags (n+3)
A tag list of all the tags associated to each question in the questionnaire.
Note - Different Fields: In the response JSON you will see two tag attributes: “questionTags” and “tags”. The below section refers to the “tags” attribute only as this contains the more relevant information for the API integration.
Field Table
Field | Description | Data Type |
id | The ID for the tag within the question | string |
name | The text value of the tag name | string |
isVisible | If the tag is visible in the front-end questionnaire response portal. | boolean |
isException | Not in use | boolean |
groupId | The ID of the tag group the tag belongs too | string |
group | Single array list item with details about the tag group the tag belongs too. | array |
Schema
{
...
"tags": [{
"id": "string",
"name": "string",
"isVisible": boolean,
"isException": boolean,
"groupId": "string",
"group": [{...}]
}]
...
}
Fourth Level: Rows (n+3) [Matrix Questions only]
This section is only relevant for Matrix type questions: A list of the rows that exist within the matrix question structure.
Note - Rows: As rows are added/removed to/from a matrix question (either via the API or CDP Portal) the row list returned by the /questions endpoint here will change accordingly. If you retrieve this data before the questionnaire-response has been updated, then you will only see the pre-set rows created by CDP as part of the questionnaire structure.
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 |
refld | The permanent ID for the row within the matrix question. | string |
complexQuestionId | The ID of the parent matrix question | string |
instanceId | Not in use | integer |
title | The name of the row | string |
order | The position of the row within the matrix question | integer |
rowTags | List of tags that have been applied at row level to the given row. | array |
tags | List of tags that have been applied at row level to the given row. | array |
Note: It is currently not possible to tell from this data alone which rows were created by a user and which are pre-set rows which cannot be deleted. As such, whenever a row is created via the API the ID should be captured.
Schema
{
...
"rows": [{
"id": "string",
"refId": "string",
"complexQuestionId": "string",
"instanceId": integer,
"title": "string",
"order": integer,
"rowTags": [{...}],
"tags": [{...}]
}]
...
}
Fourth Level: Columns (n+3) [Matrix Questions only]
This section is only relevant for Matrix type questions: A list of the columns (or child questions) that exist within the matrix question structure.
Note - Columns: The structure here is essentially a copy of the 3rd level questions data (shared above), the differences are that type cannot be “MATRIX” as you cannot have a matrix question within another matrix question. And some of the matrix specific fields are therefore not included.
Field Table
Field | Description | Data Type |
id | The ID for the current version of the child question within the questionnaire | string |
refId | The permanent ID of the child question within the questionnaire. | string |
blankOptions | Not in use | integer |
type | The question type for the given child question. | string |
isDynamic | Not in use at column level as cannot have a matrix question within a matrix question. | boolean |
isPrepop | Not in use at column level as cannot have a matrix question within a matrix question. | boolean |
allowCopyForward | Indicates if copy forward (taking answers from users previous cycle response) is enabled on the child question. | boolean |
variant | An additional control of how a question is configured which should be consider alongside “type”. See note in 3rd level question details above. | string |
validationRules | Lists out the validation rules that have been applied to the question. e.g. min/max date, character limits, numeric range, decimals. | string |
isMandatory | Indicates if the question is mandatory for submission. | boolean |
order | The position of the child question within the matrix. | integer |
code | The reference for the child questions position in the questionnaire (e.g. "1.24.2.7"). Note: matrix columns are listed as a decimal value under the parent question. This can lead to the same “code” appearing more than once. | string |
text | The main child question text. | string |
simpleHelpText | Child question help text 1 | string |
popupHelpText | Child question help text 2 | string |
sectionId | The section ID the child question is within. | string |
groupId | Not in use at column level as columns are not being grouped this cycle | string |
parentQuestionId | The id of the matrix question in which the child question sits. | string |
requestingAuthoritiesEnabled | Indicates if the requesting authorities are returned in the portal as part of the options list. Note: the option list will not be populated via the API. | boolean |
rowTitle | Not in use | string |
questionTags | List of tags that have been applied at child question level to the given child question. | array |
Tags | List of tags that have been applied at child question level to the given child question. | array |
options | For single and multi-select questions: a list of available options for the question. | array |
optionGroups | For grouped questions: a list of available groups for the question. | array |
Schema
{
...
"columns": [{
"id": "string",
"refId": "string",
"blankOptions": integer,
“type": "string",
"isDynamic": boolean,
"isPrepop": boolean,
"allowCopyForward": boolean,
"variant": "string",
"validationRules": "string",
"isMandatory": boolean,
"order": integer,
"code": "string",
"text": "string",
"simpleHelpText": "string",
"popupHelpText": "string",
"sectionId": "string",
"groupId": null,
"parentQuestionId": "string",
"requestingAuthoritiesEnabled": boolean,
"rowTitle": "string",
"questionTags": [{...}],
"tags": [...}],
"options": [{...}],
"optionGroups": [...}]
}]
...
}
POST/PUT/DELETE Requests
POST, PUT and DELETE requests are not implemented for this endpoint, preventing changes being made to a Discloser’s questionnaire structure.
If you have not found the answer you were looking for, please contact your account manager who will be able to assist you further.