Policy questions

During a submission, questions may have been posed to the insured. These questions could have been used to pre-qualify the account, or to get additional information about a specific location. These questions and their answers are available from the policy once the policy has been bound.

Questions can be optional, and it is possible for no answer to be provided to a question. From the policy, you can see all the questions that were part of the submission, whether they were answered or not. You can also see any answers that were provided.

Querying for questions and their answers

Use the following endpoints to retrieve information about a set of questions and their answers, if any.

Endpoint Response
GET /policies/{policyId}/questions The set of policy-level questions from the job (which are typically used for pre-qualification), and their answers, if any
GET /policies/{policyId}/locations/{locationId}/questions The set of location-level questions for the specified location from the job (which are typically used to gather additional information for rating), and their answers, if any

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 this variation in the datatype of an answer, a QuestionAnswer has a questionType property. This identifies the datatype of the answer. This property 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.

For example, if a QuestionAnswer's questionType is set to Boolean, then the answer is stored in the booleanValue field. The choiceValue, dateValue, integerValue, and textValue properties are set to null.

If no answer was specified for a question, there is still a QuestionAnswer for the question, 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 request 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.

Property How the value is set
question Always included. It contains the id of the question and the displayName, which is the text shown on the user interface to pose the question.
questionType Always included. It contains the questionTypeCode, which is one of the following: Boolean, Choice, Date, Integer, String
displayValue Set to the display value of the answer, if the question has an answer. Otherwise, set to null and omitted from the response.
booleanValue Set to a Boolean value if the questionType is Boolean and the question has been answered. Otherwise, set to null and omitted from the response.
choiceValue Set to a choiceValueCode if the questionType is Choice and the question has been answered. Otherwise, set to null and omitted from the response. (The acceptable choiceValueCode values for a given question are defined in the product definition and can vary from question to question.)
dateValue Set to a date value if the questionType is Date and the question has been answered. Otherwise, set to null and omitted from the response.
integerValue Set to an integer value if the questionType is Integer and the question has been answered. Otherwise, set to null and omitted from the response.
textValue Set to a string value if the questionType is String and the question has been answered. Otherwise, set to null and omitted from the response.

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