How to Build A Survey with Both HMIS and Custom Questions

How to create a survey and a section within it

1. Create Survey: POST /v2/surveys
   • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_v2-surveys
2. Create Sections for the survey: POST /surveys/{surveyid}/surveysections
   • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_surveys-surveyid-surveysections

How to modify / update a survey

• API is not available for copying an existing survey to a new one in one API call, but it could be scripted on the client side, which we have seen performed successfully, easily enough
• API to modify an existing survey: PUT /v2/surveys/{surveyid}

How to create custom questions

1. First we need to create a question group. A question group is only a logical grouping of questions, so it's easier to FETCH questions for a question group and then associate them with the survey. For instance, all the household income related questions can be part of a question group.
   • API POST /questiongroups
   • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_questiongroups
2. Create questions in a group:
   • API: POST /v2/questiongroups/{questiongroupid}/questions
   • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_v2-questiongroups-questiongroupid-questions

How to add custom questions to a survey

1. Within a question group, but within a section
2. Within a question group, but not using a section (is this possible?)

How to use a hard-coded 2020 HMIS question in a survey section

• There are two ways to set up HMIS questions in a survey section 1.1. GET the HUD questions (API is available to get the HUD questions specific to each schema) and then create Survey questions.
  • API: GET /v2/questions
  • Doc: /https://docs.hslynk.com/?urls.primaryName=2020%20Apis#/default/GET_questions_V2 1.2. Create Questions using the response from the above
  • API: POST /v2/questiongroups/{questiongroupid}/questions
  • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_v2-questiongroups-questiongroupid-questions

2. Maintain question information in surveyDefinition attribute as Stringified JSON.
   • API: POST /v2/surveys
   • Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/POST_v2-surveys

• For actually populating the HMIS version specific schemas with responses (double-posting to the HMIS schema and to the Survey response), please see this related how-to: https://github.com/servinglynk/hslynk-open-source-docs/wiki/How-to-use-the-survey-builder-tool-in-HSLynk-to-capture-APR-reportable-HMIS-data-elements

How to copy custom questions from one survey to another

• API not available yet, though this could be scripted on the client side, which we have seen performed successfully, easily enough

How to retrieve a survey

• API: GET /v2/surveys/{surveyid}
• Doc: https://docs.hslynk.com/?urls.primaryName=Survey%20Service%20Api#/default/GET_v2-surveys-surveyid