Answering questions

Structure of a QuestionAnswer

A QuestionAnswer is a resource that stores a single question for a job or policy and its answer, if any.

The datatype of a question's answer depends on the nature of the question itself. For example, "Is the driver legally blind?" has a Boolean answer, but "What was the date of the most recent safety course completed?" has a datetime answer.

To accommodate the varying datatype of an answer, a QuestionAnswer has a questionType property. This identifies the datatype of the answer. It is set to one of the following: Boolean, Choice, Date, Integer, String.

There are also a set of datatype-specific ...Value properties: booleanValue, choiceValue, dateValue, integerValue, textValue. For a given QuestionAnswer, the answer is stored in the ...Value property that corresponds to the questionType. The ...Value properties that are not relevant are set to null.

Some questions do not require an answer. If a question has no answer, there is still a QuestionAnswer for it, but all of its ...Value properties are null.

There is also a displayValue property. This stores the question's answer, if any, converted to a string.

Structure of a /questions response

The response to a GET /questions has a single answers attribute. This attribute contains a map of QuestionAnswers. Each QuestionAnswer has the following syntax:

    "<questionId>": {
      "question": {
        "displayName": "<displayText>"
        "id": "<questionId>"
      },
      "questionType": {
        "code": "<questionTypeCode>",
      },
      "displayValue": "<value>",
      "booleanValue": <value>,
      "choiceValue": {
        "code": "<choiceValueCode",
      },
      "dateValue": "<value>",
      "integerValue": <value>,
      "textValue": "<value>",
},

For any given question, some values are always set and some values are always null. If a property has a null value, it is not included in the response. The following table defines how each value is set.

Note that for any given question that has an answer, there are four values that are included:

• question (the question id)
• questionType (the datatype of the answer)
• displayValue (the answer, rendered as a string)
• The ...Value field corresponding to the questionType (the answer, rendered as its native datatype)

Even though the QuestionAnswer schema has multiple ...Value fields, for a given QuestionAnswer that has an answer, only one of them has a value. The other ...Value fields are null. (If the question has no answer, all of the ...Value fields are null.)

Examples of answer responses

This is an example of a response to a GET /questions.

The first question, MovingViolations2, is a Boolean question. Its answer is true.

{
  "data": {
    "attributes": {
      "answers": {
        "MovingViolations2": {
          "question": {
            "displayName": "Any drivers with convictions for moving traffic violations within 
the past 3 years? If 'Yes' please explain.",
            "id": "MovingViolations2"
          },
          "questionType": {
            "code": "Boolean"
          },
          "displayValue": "true",
          "booleanValue": true
        },
...

The second question, DriverNameConviction, is a string question. Its answer is "Driving without a license".

...
        "DriverNameConviction": {
          "question": {
            "displayName": "Please provide the driver name and explain the conviction.",
            "id": "DriverNameConviction"
          },
          "questionType": {
            "code": "String"
          },
          "displayValue": "Driving without a license",
          "textValue": "Driving without a license"
        },
...

The third question, PACurrentlyInsured, is a choice question. Its answer is a question-specific code from the product design (newdriver, which has a display value of "No - New driver").

...
        "PACurrentlyInsured": {
          "question": {
            "displayName": "Is the applicant currently insured?",
            "id": "PACurrentlyInsured"
          },
          "questionType": {
            "code": "Choice"
          },
          "displayValue": "No - New Driver",

          "choiceValue": {
            "code": "newdriver",
            "name": "No - New Driver"
          }
        },
...

The fourth question, CurrentSuspense, is a Boolean question. It has not been answered, so its displayValue and booleanValue properties are null and therefore not included in the response.

...
        "CurrentSuspense": {
          "question": {
            "displayName": "Is the applicant's license currently suspended, canceled, or revoked?",
            "id": "CurrentSuspense"
          },
          "questionType": {
            "code": "Boolean"
          }
        },
...