> ## 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.

# Periods

> Learn how to define references to periods of time in the roster.

Many aspects that should be taken into consideration in producing a roster are only applicable during certain periods of time. For example, think of weekly limits for work, or the availability of employees during certain days of the week.
Specifying such periods of time is done using the `periods` field. This page explains how to configure this field for different use cases.

<Card title="Periods schema">
  <ResponseField name="periods" type="object">
    List of periods in the schedule. Periods can be defined explicitly or through a recurrent definition (for example, to generate weeks).

    <Expandable title="properties">
      <ResponseField name="days" type="object">
        List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period.
      </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>

        <ResponseField name="startTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>

        <ResponseField name="endTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>
      </Expandable>

      <ResponseField name="customDefinitions" type="array of object">
        List of custom period definitions. Each custom period definition defines one period in the schedule.
      </ResponseField>

      <Expandable title="customDefinitions – item structure">
        <ResponseField name="startDay" type="object">
          Describes one day in the schedule.
        </ResponseField>

        <Expandable title="startDay – properties">
          <ResponseField name="date" type="string (date)">
            Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
          </ResponseField>

          <ResponseField name="dayIndex" type="integer">
            Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
          </ResponseField>
        </Expandable>

        <ResponseField name="endDay" type="object">
          Describes one day in the schedule.
        </ResponseField>

        <Expandable title="endDay – properties">
          <ResponseField name="date" type="string (date)">
            Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
          </ResponseField>

          <ResponseField name="dayIndex" type="integer">
            Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
          </ResponseField>
        </Expandable>

        <ResponseField name="startTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>

        <ResponseField name="endTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>

        <ResponseField name="applyTimeToAllDays" type="boolean">
          If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
        </ResponseField>
      </Expandable>

      <ResponseField name="recurrentDefinition" type="object">
        A recurrent definition to easily create a set of similar periods.
      </ResponseField>

      <Expandable title="recurrentDefinition – properties">
        <ResponseField name="daysPerPeriod" type="integer" required>
          The number of days in each period.
        </ResponseField>

        <ResponseField name="daysBetweenStarts" type="integer">
          The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods.
        </ResponseField>

        <ResponseField name="startDay" type="object">
          Describes one day in the schedule.
        </ResponseField>

        <Expandable title="startDay – properties">
          <ResponseField name="date" type="string (date)">
            Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
          </ResponseField>

          <ResponseField name="dayIndex" type="integer">
            Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
          </ResponseField>
        </Expandable>

        <ResponseField name="endDay" type="object">
          Describes one day in the schedule.
        </ResponseField>

        <Expandable title="endDay – properties">
          <ResponseField name="date" type="string (date)">
            Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
          </ResponseField>

          <ResponseField name="dayIndex" type="integer">
            Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
          </ResponseField>
        </Expandable>

        <ResponseField name="startTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>

        <ResponseField name="endTime" type="string (time)">
          TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
        </ResponseField>

        <ResponseField name="applyTimeToAllDays" type="boolean">
          If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
        </ResponseField>
      </Expandable>

      <ResponseField name="labels" type="array of string">
        Provide labels to re-use periods that were defined in the configuration.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Card>

## Periods created through days

The most basic way to define periods is to refer to specific days in the roster. This is done by using the `days` field in the `periods` object.

Within this object, you can specify specific days using `dates` (in `CALENDAR` payloads) or `dayIndices` (in `RECURRING` payloads).

```json title="Referring to specific days using dates" theme={null}
{
  "periods": {
    "days": {
      "dates": ["2026-01-01", "2026-01-02", "2026-01-05"]
    }
  }
}
```

### Days of the week

Alternatively, you can specify the days of the week using `daysOfWeek`. For example, the following periods definition will refer to all Wednesdays and Fridays in the roster.

```json title="Referring to specific days using days of week" theme={null}
{
  "periods": {
    "days": {
      "daysOfWeek": ["WED", "FRI"]
    }
  }
}
```

### Start and end times

Finally, you can add a `startTime` and `endTime` to the `days` object to specify a time interval during the day. For example, the following periods definition will refer to all evenings on Wednesdays and Fridays.
This could be useful for instance to specify that an employee is not available for work during these times (though they are still available for work earlier in these days).

```json title="Referring to specific days using days of week and time interval" highlight="5-6" theme={null}
{
  "periods": {
    "days": {
      "daysOfWeek": ["WED", "FRI"],
      "startTime": "18:00",
      "endTime": "23:00"
    }
  }
}
```

<Info>
  Creating periods through days will always consider each day in the roster as a
  separate period. This is relevant for some rules where the targets of the
  rule are applied to each period separately.
</Info>

## Periods created through custom definitions

If you need to create periods consisting of multiple days, you can use the `customDefinitions` field in the `periods` object. These are defined through a start and end day (and optionally a start and end time).
For example, the following periods definition will refer to the period from January 1st to January 5th and the period from February 10th to February 14th.

```json title="Referring to a custom period using start and end days" theme={null}
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-05"
        }
      },
      {
        "startDay": {
          "date": "2026-02-10"
        },
        "endDay": {
          "date": "2026-02-14"
        }
      }
    ]
  }
}
```

### Start and end times

Similarly to the `days` field, you can also add a `startTime` and `endTime` to the `customDefinitions` object to specify a time interval during the day.
For example, the following periods definition will refer to the period from 10:00 on January 1st to 18:00 on January 5th.

```json title="Referring to a custom period using start and end days and time interval" highlight="11-12" theme={null}
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-05"
        },
        "startTime": "10:00",
        "endTime": "18:00"
      }
    ]
  }
}
```

### Applying time to all days

Finally, custom period definitions allow you to choose whether the start and end time should apply to each day individually.
For example, the following periods definition will refer to all periods of time between 20:00 and 06:00 on every day between January 1st and January 31st.

```json title="Referring to a custom period using start and end days and time interval and applying time to all days" highlight="13" theme={null}
{
  "periods": {
    "customDefinitions": [
      {
        "startDay": {
          "date": "2026-01-01"
        },
        "endDay": {
          "date": "2026-01-31"
        },
        "startTime": "20:00",
        "endTime": "06:00",
        "applyTimeToAllDays": true
      }
    ]
  }
}
```

By default, `applyTimeToAllDays` is set to `false`.

## Periods created through recurrent definitions

If you want to create periods that are all the same length, the `recurrentDefinition` field might suit your needs. For example, if you want to create a rule that applies on a weekly basis, the recurrent definition allows you to
easily specify this without having to define each week by its exact start and end days.

For example, the following recurrent definition will create a non-overlapping set of periods that are each 7 days long, starting from the first day and continuing until the last day of the roster.

```json title="Defining weekly periods using a recurrent definition" theme={null}
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7
    }
  }
}
```

### Restricting the range of periods

If you only need your recurrent definition to create periods for a certain range within your roster, you can also specify the `startDay` and `endDay` properties.
For example, the following recurrent definition will create a non-overlapping set of periods that are each 7 days long, starting from April 1st and continuing until June 30th.

```json title="Defining weekly periods for a specific range" highlight="6,9" theme={null}
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7,
      "startDay": {
        "date": "2026-04-01"
      },
      "endDay": {
        "date": "2026-06-30"
      }
    }
  }
}
```

### Overlapping and non-consecutive periods

By default, periods created through a recurrent definition will be non-overlapping and consecutive. If you want to create a sliding window of periods, you can use the
`daysBetweenStarts` property. For example, we could use the following periods on a rule to make sure that an employee never works more than 40 hours in *any* 7-day period.

```json title="Defining weekly periods with a sliding window" highlight="5" theme={null}
{
  "periods": {
    "recurrentDefinition": {
      "daysPerPeriod": 7,
      "daysBetweenStarts": 1
    }
  }
}
```

### Start and end times

Recurrent definitions allow for the use of start and end time similarly to custom definitions. This example shows a recurrent definition for weekend periods that start Friday afternoon and last until Sunday night.

```json title="Defining weekend periods with a start and end time" highlight="9-10" theme={null}
{
  "periods": {
    "recurrentDefinition": {
      "startDay": {
        "date": "2026-01-02" // Start on the first Friday of the roster
      },
      "daysPerPeriod": 3, // Periods last Friday-Sunday
      "daysBetweenStarts": 7,
      "startTime": "18:00", // Starts at 6pm on Friday
      "endTime": "22:00" // Ends at 10pm on Sunday
    }
  }
}
```

## Period labels

If there are periods that are useful in multiple rules, you can define them in `extensions.labeling.periods`.
This can greatly reduce the size of your payloads when handled properly, and it can be smart to identify which periods are applicable for this within your integration.

<Tip>
  Some commonly reused periods are for example weekends, weekdays, public
  holidays and nights.
</Tip>

The below example shows how to define labels for weekends and then reuse them on an availability rule to make it undesirable for employees to work on weekends.

```json title="Defining labels for commonly reused periods" highlight="6, 23" theme={null}
{
  "extensions": {
    "labeling": {
      "periods": [
        {
          "label": "WEEKENDS",
          "periods": {
            "days": {
              "daysOfWeek": ["SAT", "SUN"]
            }
          }
        }
      ]
    }
  },
  "rules": {
    "availabilityRules": [
      {
        "id": "weekend-availability",
        "importance": "HIGH",
        "isDesired": false,
        "periods": {
          "labels": ["WEEKENDS"]
        }
      }
    ]
  }
}
```