Skip to content

Questionnaires API (1.0)

Provides access to the questionnaires that is part of a Hyperproof organization.

Languages
Servers
Mock server
https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi
Hyperproof US
https://api.hyperproof.app/v1/questionnaires
Hyperproof Gov
https://api.hyperproofgov.app/v1/questionnaires
Hyperproof EU
https://api.hyperproof.eu/v1/questionnaires

Get Questionnaires

Request

GET /

Description

Retrieves all questionnaires within an organization, including their titles, versions, and associated metadata.

Security
oauth2
Query
statusstring

Filters results by the provided object status

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/?status=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring

The unique identifier for the questionnaire

Example: "d88d505d-5199-11ee-a644-522476618ae8"
namestring

The name of the questionnaire

Example: "Vendor Questionnaire"
versioninteger

The version of the questionnaire

calculateRiskboolean

Whether to calculate risk for this questionnaire

Example: true
accessTypestring

The method in which the questionnaire is accessed by the recipient

Enum"invitation""sharedLink"
Example: "invitation"
targetObjectTypestring

The type of object the questionnaire is associated with

Enum"vendor""riskRegister""assessment"
Example: "vendor"
targetObjectIdstring(uuid)

Optional unique identifier of an object the questionnaire is directly associated too

createdObjectTypestring

The type of object created when a questionnaire is submitted (i.e. risk intake survey)

Value"risk"
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the questionnaire

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the questionnaire was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the questionnaire

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the questionnaire was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the questionnaire

Example: []
]
Response
application/json
[ { "id": "d88d505d-5199-11ee-a644-522476618ae8", "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8", "name": "Vendor Questionnaire", "calculateRisk": true, "version": 0, "accessType": "invitation", "targetObjectType": "vendor", "targetObjectId": "", "status": "active", "createdBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "createdOn": "2023-09-12T18:26:10.0053650+00:00", "updatedBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "updatedOn": "2023-09-12T18:26:10.0053650+00:00", "permissions": [] } ]

Send Questionnaire

Request

PUT /{questionnaireId}/send

Description

Sends a questionnaire to a specified recipient or set of recipients, initiating the response process and tracking delivery status.

Security
oauth2
Path
questionnaireIdstringrequired

Unique ID of the questionnaire to send

Bodyapplication/json
objectTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
invitedToIdstring(uuid)required

The unique identifier of the questionnaire to send.

Example: "42310868-81f9-48c3-b68a-6582495c36b7"
versionintegerrequired

The version of the questionnaire to send.

objectInfoArray of objects(QuestionnaireInvitationObjectInfo)required

Information about who the questionnaire invitation is being sent to and for what vendor.

Example: [{"objectId":"859c5f4f-734d-4c7f-9673-efa7f30e4da8","ownerId":"75c7a61b-0366-48d4-843a-e9ff69292793","respondentType":"owner"}]
objectInfo[].​objectIdstring(uuid)required

The unique identifier of the object to send the questionnaire to, e.g. vendor id.

Example: "859c5f4f-734d-4c7f-9673-efa7f30e4da8"
objectInfo[].​ownerIdstring(uuid)required

The unique identifier of the owner of the object when respondentType is owner or ownerAndContact.

Example: "75c7a61b-0366-48d4-843a-e9ff69292793"
objectInfo[].​contactIdsArray of strings(uuid)

The unique identifiers of the contacts to send the questionnaire to when respondentType is contact or ownerAndContact.

Example: ["f5a7ad1b-0366-48dc-842a-e9ff6zb92a45"]
objectInfo[].​respondentTypestring(QuestionnaireRespondentType)required

The type of respondent for the questionnaire invitation.

Enum"owner""contact""ownerAndContact"
curl -i -X PUT \
  'https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/{questionnaireId}/send' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invitedToId": "42310868-81f9-48c3-b68a-6582495c36b7",
    "objectInfo": [
      {
        "objectId": "859c5f4f-734d-4c7f-9673-efa7f30e4da8",
        "ownerId": "75c7a61b-0366-48d4-843a-e9ff69292793",
        "respondentType": "owner"
      }
    ],
    "objectType": "vendor",
    "version": 0
  }'

Responses

Success.

Bodyapplication/jsonArray [
questionnaireIdstring(uuid)

The unique identifier for the questionnaire.

Example: "d297b753-05da-46bb-8558-15177350d244"
invitationIdstring(uuid)

The unique identifier for the questionnaire invitation.

Example: "8a0c64fa-1bff-4741-a332-dc7458f7144a"
versioninteger

The version of the questionnaire.

vendorIdstring(uuid)

The unique identifier for the vendor.

vendorNamestring

The name of the vendor.

Example: "Acme"
contactGivenNamestring

The given name of the person the questionnaire was sent to.

contactSurnamestring

The surname of the person the questionniare was sent to.

contactEmailstring

The email address of the person the questionnaire was sent to.

QuestionnaireStatusstring(QuestionnaireStatus)

The completion status of the questionnaire.

Enum"sent""inProgress""completed""unlocked""closed"
QuestionnaireInvitationUserTypestring(QuestionnaireInvitationUserType)

The type of user the questionnaire was sent to (i.e. Owner or External Contact).

Enum"owner""externalObjectContact"
latestResponseVersioninteger

The latest version of the responses.

recipientsArray of objects(QuestionnaireInvitationRecipientCollection)

Collection of invitation recipients

Example: [{"name":"John Doe","email":"John@hyperproof.io"}]
reminderCountinteger

The count of reminders that have been sent for this questionnaire invitation.

dateLastSentstring

The date the questionnaire invitation was last sent (ISO-8601 format).

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring(date-time)

The date the questionnaire invitation was created (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring(date-time)

The date the questionnaire invitation was updated (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the question condition.

Example: []
]
Response
application/json
[ { "id": "5ba459d0-c69a-4ba3-b5d7-572c56838bfe", "orgId": "5bf47cef-6a4f-4ed1-aa8a-9a9cf6e2b831", "invitationId": "8a0c64fa-1bff-4741-a332-dc7458f7144a", "questionnaireId": "d297b753-05da-46bb-8558-15177350d244", "questionaireStatus": "sent", "invitationUserType": "owner", "version": 0, "latestResponseVersion": 0, "recipients": [], "vendorName": "Acme", "status": "active", "createdBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "createdOn": "2023-09-12T18:26:10.0053650+00:00", "updatedBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "updatedOn": "2023-09-12T18:26:10.0053650+00:00", "permissions": [] } ]

Get Questionnaire Invites Filtered

Request

PUT /invitations/filter

Description

Retrieves a list of questionnaire invitations that match the specified filter criteria, such as status, recipient, or questionnaire type.

Security
oauth2
Bodyapplication/json
questionnaireIdsArray of strings

The unique identifiers of the questionnaires to filter the questionnaire invitations.

Example: ["a3f96b88-51a8-4db0-9403-a40b8b6d92e4","cf09a1f6-3bcc-4e71-9c56-11bb83bf57d6"]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
curl -i -X PUT \
  https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/invitations/filter \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "questionnaireIds": [
      "a3f96b88-51a8-4db0-9403-a40b8b6d92e4",
      "cf09a1f6-3bcc-4e71-9c56-11bb83bf57d6"
    ],
    "status": "active"
  }'

Responses

Success.

Bodyapplication/jsonArray [
questionnaireIdstring(uuid)

The unique identifier for the questionnaire.

Example: "d297b753-05da-46bb-8558-15177350d244"
invitationIdstring(uuid)

The unique identifier for the questionnaire invitation.

Example: "8a0c64fa-1bff-4741-a332-dc7458f7144a"
versioninteger

The version of the questionnaire.

vendorIdstring(uuid)

The unique identifier for the vendor.

vendorNamestring

The name of the vendor.

Example: "Acme"
contactGivenNamestring

The given name of the person the questionnaire was sent to.

contactSurnamestring

The surname of the person the questionniare was sent to.

contactEmailstring

The email address of the person the questionnaire was sent to.

QuestionnaireStatusstring(QuestionnaireStatus)

The completion status of the questionnaire.

Enum"sent""inProgress""completed""unlocked""closed"
QuestionnaireInvitationUserTypestring(QuestionnaireInvitationUserType)

The type of user the questionnaire was sent to (i.e. Owner or External Contact).

Enum"owner""externalObjectContact"
latestResponseVersioninteger

The latest version of the responses.

recipientsArray of objects(QuestionnaireInvitationRecipientCollection)

Collection of invitation recipients

Example: [{"name":"John Doe","email":"John@hyperproof.io"}]
reminderCountinteger

The count of reminders that have been sent for this questionnaire invitation.

dateLastSentstring

The date the questionnaire invitation was last sent (ISO-8601 format).

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring(date-time)

The date the questionnaire invitation was created (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring(date-time)

The date the questionnaire invitation was updated (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the question condition.

Example: []
]
Response
application/json
[ { "id": "5ba459d0-c69a-4ba3-b5d7-572c56838bfe", "orgId": "5bf47cef-6a4f-4ed1-aa8a-9a9cf6e2b831", "invitationId": "8a0c64fa-1bff-4741-a332-dc7458f7144a", "questionnaireId": "d297b753-05da-46bb-8558-15177350d244", "questionaireStatus": "sent", "invitationUserType": "owner", "version": 0, "latestResponseVersion": 0, "recipients": [], "vendorName": "Acme", "status": "active", "createdBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "createdOn": "2023-09-12T18:26:10.0053650+00:00", "updatedBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "updatedOn": "2023-09-12T18:26:10.0053650+00:00", "permissions": [] } ]

Send Questionnaire Reminder

Request

PUT /{questionnaireId}/invitations/{invitationId}/remind

Description

Sends a reminder notification for a specified questionnaire to prompt recipients to complete their responses.

Security
oauth2
Path
questionnaireIdstringrequired

Unique ID of the questionnaire

invitationIdstringrequired

Unique ID of the invitation

curl -i -X PUT \
  'https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/{questionnaireId}/invitations/{invitationId}/remind' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/json
questionnaireIdstring(uuid)

The unique identifier for the questionnaire.

Example: "d297b753-05da-46bb-8558-15177350d244"
invitationIdstring(uuid)

The unique identifier for the questionnaire invitation.

Example: "8a0c64fa-1bff-4741-a332-dc7458f7144a"
versioninteger

The version of the questionnaire.

vendorIdstring(uuid)

The unique identifier for the vendor.

vendorNamestring

The name of the vendor.

Example: "Acme"
contactGivenNamestring

The given name of the person the questionnaire was sent to.

contactSurnamestring

The surname of the person the questionniare was sent to.

contactEmailstring

The email address of the person the questionnaire was sent to.

QuestionnaireStatusstring(QuestionnaireStatus)

The completion status of the questionnaire.

Enum"sent""inProgress""completed""unlocked""closed"
QuestionnaireInvitationUserTypestring(QuestionnaireInvitationUserType)

The type of user the questionnaire was sent to (i.e. Owner or External Contact).

Enum"owner""externalObjectContact"
latestResponseVersioninteger

The latest version of the responses.

recipientsArray of objects(QuestionnaireInvitationRecipientCollection)

Collection of invitation recipients

Example: [{"name":"John Doe","email":"John@hyperproof.io"}]
reminderCountinteger

The count of reminders that have been sent for this questionnaire invitation.

dateLastSentstring

The date the questionnaire invitation was last sent (ISO-8601 format).

statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring(date-time)

The date the questionnaire invitation was created (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the questionnaire invitation.

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring(date-time)

The date the questionnaire invitation was updated (ISO-8601 format).

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the question condition.

Example: []
Response
application/json
{ "id": "5ba459d0-c69a-4ba3-b5d7-572c56838bfe", "orgId": "5bf47cef-6a4f-4ed1-aa8a-9a9cf6e2b831", "invitationId": "8a0c64fa-1bff-4741-a332-dc7458f7144a", "questionnaireId": "d297b753-05da-46bb-8558-15177350d244", "questionaireStatus": "sent", "invitationUserType": "owner", "version": 0, "latestResponseVersion": 0, "recipients": [ {}, {} ], "vendorName": "Acme", "status": "active", "createdBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "createdOn": "2023-09-12T18:26:10.0053650+00:00", "updatedBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "updatedOn": "2023-09-12T18:26:10.0053650+00:00", "permissions": [] }

Get Questionnaire

Request

GET /{questionnaireId}

Description

Retrieves details of a specific questionnaire in an organization by its ID, including its title, version, and associated metadata.

Security
oauth2
Path
questionnaireIdstringrequired

Unique ID of the questionnaire to retrieve.

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/{questionnaireId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/json
idstring

The unique identifier for the questionnaire

Example: "d88d505d-5199-11ee-a644-522476618ae8"
namestring

The name of the questionnaire

Example: "Vendor Questionnaire"
versioninteger

The version of the questionnaire

calculateRiskboolean

Whether to calculate risk for this questionnaire

Example: true
accessTypestring

The method in which the questionnaire is accessed by the recipient

Enum"invitation""sharedLink"
Example: "invitation"
targetObjectTypestring

The type of object the questionnaire is associated with

Enum"vendor""riskRegister""assessment"
Example: "vendor"
targetObjectIdstring(uuid)

Optional unique identifier of an object the questionnaire is directly associated too

createdObjectTypestring

The type of object created when a questionnaire is submitted (i.e. risk intake survey)

Value"risk"
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the questionnaire

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
createdOnstring

The date the questionnaire was created (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
updatedBystring

The unique identifier of the user who last updated the questionnaire

Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"
updatedOnstring

The date the questionnaire was updated (ISO-8601 format)

Example: "2023-09-12T18:26:10.005365Z"
permissionsArray of strings

List of permissions the API user has on the questionnaire

Example: []
Response
application/json
{ "id": "d88d505d-5199-11ee-a644-522476618ae8", "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8", "name": "Vendor Questionnaire", "calculateRisk": true, "version": 0, "accessType": "invitation", "targetObjectType": "vendor", "targetObjectId": "", "status": "active", "createdBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "createdOn": "2023-09-12T18:26:10.0053650+00:00", "updatedBy": "82d7c228-8bcd-11e9-a94b-ab3de8494987", "updatedOn": "2023-09-12T18:26:10.0053650+00:00", "permissions": [] }

Get Questionnaire Questions

Request

GET /{questionnaireId}/questions

Description

Retrieves all questions from the latest version of a specified questionnaire, including their text, type, and configuration details.

Security
oauth2
Path
questionnaireIdstringrequired

Unique ID of the questionnaire

Query
versioninteger

The version of the questionnaire to retrieve questions from

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/questionnaires/questionnaires.openapi/{questionnaireId}/questions?version=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success.

Bodyapplication/jsonArray [
idstring

The unique identifier for the question.

Example: "0f5912e8-760e-11ef-8ae2-92105719a406"
orgIdstring

The unique identifier for the organization.

Example: "1dbe4d61-d8b2-11e9-9131-83d3f7zez54a"
optionsstring

The list of options if the question is of type single select or multi-select.

Example: ["Verified","Unverified"]
scoresstring

The list of scores relative to the list of options. Relevant for the overall scoring of the questionnaire.

Example: [1,0]
questionnaireIdstring

The unique identifier for the questionnaire the question belongs to.

Example: "0f580176-760e-11ef-8ae2-9210571za406"
questionnaireVersionIdstring

The unique identifier for the questionnaire version the question belongs to.

Example: "0f5876a7-760e-11ef-8ae2-9210z719a406"
questionnaireVersioninteger

The version number for the questionnaire version the question belongs to.

sectionNamestring

The name of the section in the questionnaire the question belongs to.

Example: "Vendors"
questionTypestring(QuestionType)

The type of question this is.

Enum"text""number""date""textSingleSelect""textMultiSelect""textSingleSelectAndExplanation""textMultiSelectAndExplanation""proofUpload""textInstruction"
identifierstring

Represents a question number or other identifier. This value is unique within a questionnaire section.

Example: "Vendor Verification"
contentstring

The content of the question (i.e. what is being asked).

Example: "Is this vendor verified?"
isRequiredboolean

Whether the question is required to be answered.

Example: "false,"
weightinteger

The weight of the question to relate the level of importance of a question in impacting the overall score of the questionnaire.

orderinginteger

The ordering of the question within the questionnaire.

isProofRequiredboolean

Whether the question requires an attachment.

isSystemProtectedbooleanread-only

Indicates whether this question is managed by Hyperproof. This is typically only true for questionnaires that come pre-packaged by the system and related to questions needed to generate core object properties

objectPropertyMappingKeystring(ObjectPropertyMapping)

An object and property mapping

Enum"RISK_NAME""RISK_DESCRIPTION""RISK_LIKELIHOOD_RATIONALE""RISK_IMPACT_RATIONALE""EXTERNAL_CONTACT_GIVEN_NAME""EXTERNAL_CONTACT_SURNAME""EXTERNAL_CONTACT_EMAIL"
conditionsArray of objects(QuestionConditionCollection)

The list of conditions used for displaying conditional questions.

Example: [[{"id":"d88d505d-5199-11ee-a644-522476618ae8","orgId":"ce83e3cd-5199-11ee-a644-522476618ae8","gatingQuestionId":"88940b8d-7263-438d-97ae-ea69ff9799ef","conditionalQuestionId":"4d3ebff6-6890-435d-9e8d-8842e8593d51","trigger":"yes","status":"active","createdBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","createdOn":"2023-09-12T18:26:10.005365Z","updatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","updatedOn":"2023-09-12T18:26:10.005365Z","permissions":[]}]]
statusstring(ObjectStatus)

The status of the object

Enum"active""archived"
createdBystring

The unique identifier of the user who created the question.

Example: "af5b547d-1f47-11ec-8eae-868cca974f0b"
createdOnstring

The date the question was created (ISO-8601 format).

Example: "2024-09-18T22:33:43.089359Z"
updatedBystring

The unique identifier of the user who last updated the question.

Example: "af5b547d-1f47-11ec-8eae-868cca974f0b"
updatedOnstring

The date the question was updated (ISO-8601 format).

Example: "2024-09-18T22:33:43.089359Z"
permissionsArray of strings

List of permissions the API user has on the question.

]
Response
application/json
[ { "id": "0f5912e8-760e-11ef-8ae2-92105719a406", "orgId": "1dbe4d61-d8b2-11e9-9131-83d3f7zez54a", "questionnaireId": "0f580176-760e-11ef-8ae2-9210571za406", "questionnaireVersionId": "0f5876a7-760e-11ef-8ae2-9210z719a406", "questionnaireVersion": 0, "sectionName": "Vendors", "type": "textMultiSelect", "identifier": "Vendor Verification", "content": "Is this vendor verified?", "isRequired": "false,", "weight": 0, "ordering": 0, "isProofRequired": "false,", "sectionIdentifierKey": "vendor-verified", "questionOrder": 0, "options": [], "scores": [], "status": "active", "createdBy": "af5b547d-1f47-11ec-8eae-868cca974f0b", "updatedBy": "af5b547d-1f47-11ec-8eae-868cca974f0b", "createdOn": "2024-09-18T22:33:43.0893590+00:00", "updatedOn": "2024-09-18T22:33:43.0893590+00:00" } ]