Questionnaire items and answers

Questionnaire items are identified by linkId. Your integration should use the compact questionnaire returned on each authorization as the answer contract instead of assuming one global field list.

Some fields are common across routes, such as patient, subscriber, coverage, request, provider, service, diagnosis, and procedure data. Other fields are template-specific payer questions. Treat the returned questionnaire as the contract for the current authorization.

Item shape

1
{
2
  "linkId": "diagnoses",
3
  "text": "Diagnoses",
4
  "type": "group",
5
  "required": true,
6
  "repeats": true,
7
  "minOccurs": 1,
8
  "maxOccurs": 12,
9
  "item": [
10
    {
11
      "linkId": "code",
12
      "text": "Diagnosis Code",
13
      "type": "string",
14
      "required": true
15
    },
16
    {
17
      "linkId": "qualifierCode",
18
      "text": "Diagnosis Qualifier",
19
      "type": "choice",
20
      "required": true,
21
      "options": [
22
        { "code": "ABF", "display": "ICD-10" }
23
      ]
24
    }
25
  ]
26
}

Repeated sections are represented once in the questionnaire. Do not pre-expand repeat capacity into public linkIds such as diagnoses.0.code.

Answer value shapes

Leaf items carry answer. Group items carry nested item.

1
{
2
  "answers": {
3
    "item": [
4
      { "linkId": "patient.first_name", "answer": [{ "valueString": "Jane" }] },
5
      { "linkId": "patient.date_of_birth", "answer": [{ "valueDate": "1980-01-31" }] },
6
      { "linkId": "request.is_urgent", "answer": [{ "valueBoolean": false }] },
7
      { "linkId": "service.quantity.value", "answer": [{ "valueDecimal": 2 }] },
8
      { "linkId": "request.urgency", "answer": [{ "valueCoding": { "code": "standard" } }] },
9
      {
10
        "linkId": "diagnoses",
11
        "item": [
12
          { "linkId": "code", "answer": [{ "valueString": "M06.9" }] },
13
          { "linkId": "qualifierCode", "answer": [{ "valueCoding": { "code": "ABF" } }] }
14
        ]
15
      }
16
    ]
17
  }
18
}

For coded answers, submit the option code from the questionnaire. Display labels are presentation text, not submitted values.

To submit multiple occurrences of a repeated group, include multiple sibling items with the same group linkId.

1
{
2
  "answers": {
3
    "item": [
4
      {
5
        "linkId": "diagnoses",
6
        "item": [
7
          { "linkId": "code", "answer": [{ "valueString": "M06.9" }] },
8
          { "linkId": "qualifierCode", "answer": [{ "valueCoding": { "code": "ABF" } }] }
9
        ]
10
      },
11
      {
12
        "linkId": "diagnoses",
13
        "item": [
14
          { "linkId": "code", "answer": [{ "valueString": "E11.9" }] },
15
          { "linkId": "qualifierCode", "answer": [{ "valueCoding": { "code": "ABF" } }] }
16
        ]
17
      }
18
    ]
19
  }
20
}

Requirements

requirements.questions points to questionnaire items blocking progress. For repeatable groups, path identifies the concrete occurrence while linkId points to the compact item key.

1
{
2
  "questions": [
3
    {
4
      "linkId": "code",
5
      "path": "diagnoses[0].code",
6
      "message": "Diagnosis Code is required."
7
    }
8
  ]
9
}

requirements.documents points to document types you should satisfy with attachments.

1
{
2
  "documents": [
3
    { "type": "clinical_notes", "message": "Clinical notes are required." }
4
  ]
5
}

Use the document type values as documentTypes when attaching files.

LinkId guidance

• Store mappings by payerId, coverageState, requestType, service code system, and service code when your source system maps fields differently by route.
• Prefer the current returned questionnaire over hard-coded assumptions.
• Do not treat q.*, route-specific dotted IDs, or child group linkIds as shared across payers without the enclosing questionnaire context.
• Treat a changed linkId on a returned questionnaire as a contract change for that route.
• Patch partial answers. You do not need to resend every answer on every edit.
• Do not submit flat indexed repeat slots like diagnoses.0.code; nested group answers are the public contract.

Common examples

These examples are common patterns, not a complete universal schema. Repeated concepts are groups, not indexed flat fields.

Always prefer the exact linkId returned by the authorization over an example from this table.