Some biomarkers require answers to clinical questions, this is referred to as AOE. These can be as simple as the volume of a particular marker, or the ethnicity of the patient.

Questions that are related to fasting (e.g code FSTING) do not need to be answered. Vital uses the default value you provided for fasting at the lab test creation time. However, if you do answer them, then the answered value overrides the preset test value.

There are 4 types of AOE:

  1. choice
  2. multiple_choice
  3. numeric
  4. text

choice and multiple_choice have a set list of answers to pick from, while numeric and text don’t and are free form responses.

AOE questions can also be required or optional.

​
Where to find the questions

As these AOE are directly related to biomarkers, you can find them in the GET /v3/lab_tests/markers endpoint or in the GET /v3/lab_tests/{lab_test_id}/markers endpoint, in the aoe object.

As an example, let’s look at the Lead, Blood (Adult) marker. We have omitted some extra questions for the sake of this doc.

{
  "id": 173,
  "name": "Lead, Blood (Adult)",
  "provider_id": "007625",
  ...
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]
`

Each question has it’s own id, which will be required to answer it. The types we refer to above are an enum that is represented by type.

The answers list contains a list of possible answers in the case that type is one of choice or multiple_choice, otherwise it is empty.

required deems whether the questions MUST be answered in order for the order to be valid, otherwise a error will be shown Missing required questions - "question".

​
How to answer

Answering is done at order time, via the POST /v3/order endpoint, in the field aoe_answers.

This field has the following format:

{
    "aoe_answers": [
        {
            "marker_id": <int>,
            "question_id": <int>,
            "answer": <str>,
        }
    ]
}

You will populate this list with the answers to the questions defined in the marker object, as explained above.

The marker_id refers to the Vital marker id, and the question_id to the id of the question being answered.

For example, marker Leader, Blood (Adult), has the following data:

{
  "id": 173,
  "name": "Lead, Blood (Adult)",
  "provider_id": "007625",
  ...
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]

In order to answer the required question, you will need the marker_id which is the id field, the question_id in questions[0].id and one of the code values in the question[0].answers field.

​
Answer types

The answer field contains the actual answer to the question and it’s value will depend on the type and question itself.

  1. choice and multiple_choice

In this case, the answer should contain the code field in the list of answers provided, as shown here.

e.g The question is as follows for marker of id 173:

{
  "id": 173,
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]
}

The answer is:

{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890251,
            "answer": "LCANS4",
        }
    ]
}
  1. text

This case can encompass many responses, and depends on the question itself.

In some instances, the text case contains a constraint field. This is a string tooltip indicator of the constraints applied by the lab on this particular question.

e.g The question is as follows for marker of id 173:

{
  "id": 173,
  "questions": [
    {
      "id": 1234567890304,
      "code": "EDDATE",
      "type": "text",
      "constraint": null,
      "value": "EDD/EDC DATE",
      "answers": [],
      "required": true,
      "sequence": 2
    }, 
  ]
}

The answer is:

{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890304,
            "answer": "19900101",
        }
    ]
}
  1. numeric

In this case, the answer should be a numeric string representation of the actual value.

e.g The question is as follows for marker of id 173:

{
  "id": 173,
  "questions": [
    {
      "id": 1234567890240,
      "code": "COLVOL",
      "type": "numeric",
      "constraint": null,
      "value": "URINE VOLUME (MILLILITERS)",
      "answers": [],
      "required": true,
      "sequence": 1
    }
  ]
}

The answer is:

{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890240,
            "answer": "1000",
        }
    ]
}
Ordering a Registrable TestkitPartial Result Notifications