---
title: "Preview On Call List"
method: POST
path: "/notifications/on-call/rotations/preview"
tags: ["notification-on-call"]
---

# Preview On Call List

`POST /notifications/on-call/rotations/preview`

## Request

- Base URL: `https://api-docs.upsmith.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.upsmith.com/notifications/on-call/rotations/preview`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

A change to a list, or a new one, as it would stand, and the issues that would stop it. Saves nothing.

## Headers

- `organization-id` string, nullable
- `x-user-id` string, nullable
- `timezone` string
- `x-actor-email` string, nullable
- `x-request-source` string, nullable
- `x-operation-id` string, nullable
- `x-commit-message` string, nullable
- `x-confirmation-id` string, nullable
- `x-chat-id` string, nullable

## Request body

- OnCallListPreviewRequest: A change to try without saving it. With no ``list_id`` it is a new list, whose ``changes`` must give its name, turn length, first handoff and members; the time zone falls back to the organization's.
  - `list_id` string, nullable
  - `changes` OnCallListUpdate: The fields a change sets; the ones left out keep their value. ``first_handoff_local`` is a clock time in the list's time zone, with no offset. ``on_call_now_user_id`` says who is on call from now until the next handoff; without it, whoever is on call stays on call.
    - `name` string, nullable
    - `timezone` string, nullable
    - `turn_length_days` integer, nullable
    - `first_handoff_local` string, date-time, nullable
    - `member_user_ids` string[], nullable
    - `on_call_now_user_id` string, nullable
  - `add_swap` OnCallSwapCreate: Someone on call for ``[starts_at, ends_at)``. A time with no offset is read in the list's time zone.
    - `user_id` string, required
    - `starts_at` string, date-time, required
    - `ends_at` string, date-time, required
    - `note` string, nullable
  - `remove_swap_id` string, nullable
  - `handoffs` integer

## Response `200`

Successful Response

- OnCallListPreview: The list before and after the change. ``after`` is None when ``issues`` says why it can't be made.
  - `before` OnCallListView, required: One list as it stands at a moment. ``backup`` is the next member after whoever's regular turn it is, skipping whoever is on call. ``swaps`` are the ones running or still to come. ``warnings`` holds ``fewer_than_two`` when the list has no backup. ``rule_keys`` are the rules whose newest or active version names the list.
    - `id` string, nullable, required
    - `name` string, required
    - `timezone` string, required
    - `turn_length_days` integer, required
    - `first_handoff_local` string, date-time, required
    - `members` OnCallListMember[], required
      - `user_id` string, required
      - `name` string, required
      - `position` integer, required
      - `channels` string[]
      - `reasons` string[]
    - `on_call_now` OnCallNow, required: Whoever is on call now, and until when: the next handoff, or the end of the swap that put them on.
      - `user_id` string, required
      - `name` string, required
      - `swap_id` string, nullable
      - `until` string, date-time, nullable
    - `backup` OnCallPerson, required
      - `user_id` string, required
      - `name` string, required
    - `next_handoffs` OnCallHandoff[], required
      - `user_id` string, required
      - `name` string, required
      - `at` string, date-time, required
      - `at_local` string, date-time, required
    - `swaps` OnCallSwap[], required
      - `user_id` string, required
      - `name` string, required
      - `id` string, nullable, required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
      - `starts_at_local` string, date-time, required
      - `ends_at_local` string, date-time, required
      - `note` string, nullable
    - `warnings` string[], required
    - `rule_keys` string[], required
    - `updated_at` string, date-time, nullable
  - `after` OnCallListView, required: One list as it stands at a moment. ``backup`` is the next member after whoever's regular turn it is, skipping whoever is on call. ``swaps`` are the ones running or still to come. ``warnings`` holds ``fewer_than_two`` when the list has no backup. ``rule_keys`` are the rules whose newest or active version names the list.
    - `id` string, nullable, required
    - `name` string, required
    - `timezone` string, required
    - `turn_length_days` integer, required
    - `first_handoff_local` string, date-time, required
    - `members` OnCallListMember[], required
      - `user_id` string, required
      - `name` string, required
      - `position` integer, required
      - `channels` string[]
      - `reasons` string[]
    - `on_call_now` OnCallNow, required: Whoever is on call now, and until when: the next handoff, or the end of the swap that put them on.
      - `user_id` string, required
      - `name` string, required
      - `swap_id` string, nullable
      - `until` string, date-time, nullable
    - `backup` OnCallPerson, required
      - `user_id` string, required
      - `name` string, required
    - `next_handoffs` OnCallHandoff[], required
      - `user_id` string, required
      - `name` string, required
      - `at` string, date-time, required
      - `at_local` string, date-time, required
    - `swaps` OnCallSwap[], required
      - `user_id` string, required
      - `name` string, required
      - `id` string, nullable, required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
      - `starts_at_local` string, date-time, required
      - `ends_at_local` string, date-time, required
      - `note` string, nullable
    - `warnings` string[], required
    - `rule_keys` string[], required
    - `updated_at` string, date-time, nullable
  - `issues` OnCallListIssue[], required
    - `code` string, required
    - `user_ids` string[]
    - `swap_id` string, nullable
    - `rule_keys` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/upsmith/apis/upsmith-api.md) - [All operations](https://skmtc.dev/upsmith/apis/upsmith-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upsmith/apis/upsmith-api/revisions/86e2c2bd93af?raw)