> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/key-concepts/questionnaires-and-vouchers.md).

# Questionnaires & Vouchers

Questionnaires collect clinical intake information, and Vouchers authorize each patient to complete a specific intake flow. Neither works fully on its own — together, they determine who can begin intake, which questions they answer, and which Offerings are under review by the time a physician sees the case.

### How they work together

{% stepper %}
{% step %}

#### Configure the Questionnaire

Add the questions, Offerings, and requirements for this intake flow.
{% endstep %}

{% step %}

#### Create a Voucher

Create a single-use Voucher for the Questionnaire and applicable Offerings.
{% endstep %}

{% step %}

#### Send the onboarding URL

Send the Voucher's `onboarding_url` to the patient or open it in your product.
{% endstep %}

{% step %}

#### Review the Encounter

When the patient completes intake, review the resulting Encounter and its answers.
{% endstep %}
{% endstepper %}

## Questionnaire

A **Questionnaire** is the intake form associated with one or more Offerings, and it's what the patient actually completes during the Voucher flow. Once submitted, its answers appear on the resulting Encounter as `case_questions` in the API.

At its core, a Questionnaire brings together three things: questions, the Offerings they relate to, and the requirements that govern when each one applies. Together, these components define both the intake experience the patient goes through and the treatments that get evaluated during clinical review.

### Questionnaire components

| Component            | Purpose                                                        |
| -------------------- | -------------------------------------------------------------- |
| **Question**         | Collects a specific piece of patient information.              |
| **Related Offering** | Identifies a treatment the Questionnaire can evaluate.         |
| **Requirement**      | Controls when a Question or Offering is displayed or required. |

### Questions

Each Question has a title and description that explain what the patient should provide, and you'll choose a response type that matches the kind of information you're collecting:

* Text
* Image upload
* Single-select options
* Multi-select options
* Signature
* Yes/no
* Ordering
* Rating
* Date

Some response types support additional customization on top of this. For selectable questions, for instance, you configure Options as the specific answers a patient can choose between, and you can add images, icons, or emojis to Questions and Options to make the intake experience feel less like a form.

Beyond how a Question is presented to the patient, a few settings also shape how it's handled during clinical review:

* `is_important` makes a Question stand out, so the doctor gives it extra attention.
* `is_critical` makes a Question stand out and requires the doctor to acknowledge it before approving or rejecting the Encounter.
* `is_visible` controls whether the patient sees a Question at all. Set it to `false` for invisible Questions that still get sent to the resulting Encounter, where they can provide additional instructions to the doctor without the patient ever seeing them.

### Offerings

Associate one or more [Offerings](/partner/key-concepts/offerings.md) with a Questionnaire to define the treatments it supports. A Voucher then links that Questionnaire, and its applicable Offerings, to a specific patient's intake, and the resulting Encounter gets evaluated against those same Offerings during clinical review.

### Requirements

Requirements are what make a Questionnaire adaptive rather than static. They can show, hide, or require a given Question or Offering based on any of the following:

* Age
* Gender
* BMI
* Height and weight
* Vitals or blood pressure
* Pregnancy status
* State (for state-specific eligibility)
* Prior prescriptions
* Prior questions
* Custom metadata fields

For example, you might display blood-pressure follow-up questions only when a patient's reading comes back elevated, or limit an Offering so that only patients in eligible states can request it. Requirements can be attached to both questions and offerings, and they support complex logic through combinations of AND, OR, and NOT operators, so you're rarely limited to a single condition at a time.

{% hint style="info" %}
When building your own intake form experience, you don't need to rely on our pre-configured Questionnaires structure. Instead you can apply whatever logic and structure our clinical team approves and send us the resulting questions/offerings on the Encounter directly.
{% endhint %}

## Voucher

A **Voucher** is a single-use token that authorizes an intake flow. Despite the name, it isn't a discount or coupon — it's a way to securely authorize patients to access intake forms and create Encounters on behalf of your company.

Each Voucher links together:

* A patient (optional)
* A Questionnaire
* One or more Offerings
* A voucher expiration date

If you don't specify a patient when creating a Voucher, MDI's white-label Intake Form assumes a new patient record needs to be created, and will walk the patient through the access and demographic questions needed to set up a full profile.

{% hint style="success" %}
A typical implementation route is to collect the necessary patient details at the time of checkout, use the API to create a patient record, and create a Voucher for that patient afterward. That way you avoid collecting the same demographic details — email, address, and so on — twice over the course of your acquisition flow.
{% endhint %}

### Creating a Voucher

Create a Voucher with the following endpoint:

```http
POST https://api.mdintegrations.com/v1/partner/vouchers
{
  "hold_status": false,
  "patient_id": null,
  "questionnaire_id": "{{ questionnaireId }}",
  "case_offerings": [],
  "disease": []
}
```

The response includes an `onboarding_url` — embed it in your product, or redirect the patient there directly. Once the patient completes the flow, MDI creates the Patient and Encounter records on the back end.

For a returning patient, pass their existing `patient_id` instead of `null`. Doing so skips the demographic questions and takes the patient straight into clinical intake.

{% hint style="warning" %}
If a patient cannot open an intake flow, verify that the Voucher has not been used and is not expired.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mdintegrations.com/partner/key-concepts/questionnaires-and-vouchers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.