Views:

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

Contents

Summary

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.

URLs

Sandbox: https://api.pre.cdpgreenstar.net/asp/response/questionnaire/questions

Production: https://api.cdp.net/response/questionnaire/questions

Headers/Variables

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.

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
 

{

   ...
   "section": [{
 

       "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.

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.

 

Note - validationRules: The schema of validation is shown as below:
 

"validationRules":
"{\"limit\":null,\"lo\":null,\"hi\":null,\"decimals\":null,\"default\":null,\" numberOfAttachments\":null,\"minDate\":null,\"maxDate\":null}",
 

  • “limit”: Maximum number of characters.

  • “lo” : Lowest Numerical value of the answer.

  • “hi”: Highest Numerical value of the answer.

  • “decimals”: Decimal places.

  • “default”: The default value of the answer.

  • “numberOfAttachments” : Number of attachments permitted.

  • “minDate”: Minimum date requirement.

  • “maxDate”: Maximum date requirement.


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",
       "requestongAuthoritiesEnabled": 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 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

tags

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.


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.

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.

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",
       "requestongAuthoritiesEnabled": boolean,
       "rowTitle": "string",
       "questionTags": [{…}],
       "tags": [{…}],
       "options": [{…}],
       "optionGroups": […}]

}]
...

}
 

Error Handling

1. Invalid Subscription Key

When an incorrect or invalid subscription key is entered, the following error is displayed:
 

{
"message": "Invalid subscription key",
"error": "Unauthorized",
"statusCode": 401
}

2. Invalid Organization ID

When an incorrect or invalid organization key is entered, the following error is displayed:
 

{
"message": "Invalid organization id",
"error": "Unauthorized",
"statusCode": 401
}
 

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.

Keywords: Disclosure API, API, ASP, API Partner
Comments (0)
Add a comment