> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Demands

> Learn how to define the demands that must be covered in the roster.

Demand is the need for workforce and defines how many employees you need at work at any given time in the planning period. Specifying demands in the payload is done using the `Demands` property.

<Card title="Demand schema">
  <ResponseField name="demand" type="object">
    <Expandable title="properties">
      <ResponseField name="days" type="object">
        List of days in the schedule.
      </ResponseField>

      <Expandable title="days – properties">
        <ResponseField name="dates" type="array of date (date)">
          List of dates in the schedule. Only allowed in CALENDAR payloads.
        </ResponseField>

        <ResponseField name="dayIndices" type="array of dayIndex">
          List of day indices in the schedule. Only allowed in RECURRING payloads.
        </ResponseField>

        <ResponseField name="daysOfWeek" type="array of dayOfWeek">
          List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
        </ResponseField>
      </Expandable>

      <ResponseField name="shiftDemands" type="array of object">
        List of shift demands that exist on the days specified in the days field.
      </ResponseField>

      <Expandable title="shiftDemands – item structure">
        <ResponseField name="shiftId" type="string" required>
          Unique identifier for the shift.
        </ResponseField>

        <ResponseField name="min" type="integer">
          Minimum number of employees needed to cover the demand. We will try to cover the demand with at least this number of employees. If not specified, will be equal to ideal.
        </ResponseField>

        <ResponseField name="ideal" type="integer" required>
          Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees.
        </ResponseField>

        <ResponseField name="max" type="integer">
          Maximum number of employees needed to cover the demand. We will never assign more employees to cover the demand than this number. If not specified, will be equal to ideal.
        </ResponseField>

        <ResponseField name="attributeRequirementGroups" type="array of object">
          List of requirements on the attributes that an employee must meet to be eligible to cover this shift demand.
        </ResponseField>

        <Expandable title="attributeRequirementGroups – item structure">
          <ResponseField name="attributeRequirements" type="array of object" />

          <Expandable title="attributeRequirements – item structure">
            <ResponseField name="category" type="string">
              The category of the attribute.
            </ResponseField>

            <ResponseField name="values" type="array of string">
              The targeted values for this requirement.
            </ResponseField>

            <ResponseField name="matchType" type="string (enum: NONE | ANY | ALL)">
              Default: "ALL".
            </ResponseField>
          </Expandable>

          <ResponseField name="min" type="integer">
            Minimum number of required employees that match the requirement.
          </ResponseField>
        </Expandable>

        <ResponseField name="priority" type="number">
          Priority of this demand. Increasing a demand's priority will make it prioritized compared to other demands, but also compared to rules. Default: 1.
        </ResponseField>
      </Expandable>

      <ResponseField name="timeDemands" type="array of object">
        List of time demands that exist on the days specified in the days field.
      </ResponseField>

      <Expandable title="timeDemands – item structure">
        <ResponseField name="timeSlotId" type="string" required>
          Unique identifier for this time slot.
        </ResponseField>

        <ResponseField name="min" type="integer">
          Minimum number of employees needed to cover the demand. We will try to cover the demand with at least this number of employees. If not specified, will be equal to ideal.
        </ResponseField>

        <ResponseField name="ideal" type="integer" required>
          Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees.
        </ResponseField>

        <ResponseField name="max" type="integer">
          Maximum number of employees needed to cover the demand. We will never assign more employees to cover the demand than this number. If not specified, will be equal to ideal.
        </ResponseField>

        <ResponseField name="priority" type="number">
          Priority of this demand. Increasing a demand's priority will make it prioritized compared to other demands, but also compared to rules. Default: 1.
        </ResponseField>
      </Expandable>
    </Expandable>
  </ResponseField>
</Card>

The Automatic Rostering API allows you to define demand for workforce in two different ways:

* `ShiftDemand` allows you to specify demand by stating which shifts you need on which days, and how many people you need working those shifts.
* `TimeDemand` allows you to specify demand by stating how many employees you need at different times of day throughout your schedule. The API will then assign shifts to cover the demand at those times.

<Info>
  A request to the Automatic Rostering API should either specify all demand as `ShiftDemand`, or all demand as
  `TimeDemand`. A combination of both is currently not supported.
</Info>

Choose which type of demand suits your needs, then find below some pointers on how to configure the `Demands` object for your use case.

## ShiftDemand

If you have already configured Shifts in your request, then using these to specify `ShiftDemand` is very simple. Consider the following example.

<Tip>
  The following shows how to specify that on days 1 and 2 you require 2 people to work Shift A and 2 people to work Shift B, while on day 3 you only require 2 people working Shift B.

  ```json theme={null}
  {
    "demands": [
      {
        "days": {
          "dayIndices": [0, 1]
        },
        "shiftDemands": [
          {
            "shiftId": "shift-a",
            "ideal": 2
          },
          {
            "shiftId": "shift-b",
            "ideal": 2
          }
        ]
      },
      {
        "days": {
          "dayIndices": [2]
        },
        "shiftDemands": [
          {
            "shiftId": "shift-b",
            "ideal": 2
          }
        ]
      }
    ]
  }
  ```
</Tip>

### Attribute requirements

In principle, all employees assigned to a demand must be compatible with the [attribute](/v2/entities/employees#attributes) requirements on that demand.
However, it is also possible to specify a minimum number of assigned employees that must be compatible.

<Tip>
  The first demand requires *all* employees to be able to drive. For the second demand, *at least* one of the assigned
  employees should be a nurse.

  ```json theme={null}
  {
    "demands": [
      {
        "shiftDemands": [
          {
            "shiftId": "shift1",
            "ideal": 2,
            "attributeRequirementGroups": [
              {
                "attributeRequirements": [
                  {
                    "category": "competences",
                    "values": ["driving"]
                  }
                ]
              }
            ]
          },
          {
            "shiftId": "shift2",
            "ideal": 2,
            "attributeRequirementGroups": [
              {
                "attributeRequirements": [
                  {
                    "category": "personnelGroup",
                    "values": ["nurses"]
                  }
                ],
                "min": 1
              }
            ]
          }
        ]
      }
    ]
  }
  ```
</Tip>

## TimeDemand

When demand is defined as the time periods for when employees are needed, the solver assigns employees to the shifts that are able to cover this demand.