Returns information on the relevant sections, questions, rows and options within a questionnaire for the specified organization.
Pre-requisites: 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 details 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 on 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.
subscription-key (header):For authorized user, the 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 only the GET methods in the API will continue to allow requests.
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.
Note: use JSON.parse to clean string.
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.
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.
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 start and/or end of the string.
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.
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 organization's disclosure.
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
Indicates if the option is the “Other” option.
integer
refId
The position of the option group within the grouped option list. Numbers will be ascending values within a single option list.
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
refId
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.
array
order
The position of the row within the matrix question.
array
rowTags
List of tags that have been applied at row level to the given row.
array
Note:for dyanmic questions, if instance ID is missing then the row is pre-populated. If instance ID is present, then the row is user created. However, whenever a row is created via the API the ID should be captured.
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.
Note: use JSON.parse to clean string.
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 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 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.
