---
title: "Preview a roster + schedule import"
method: POST
path: "/api/v1/imports/preview"
tags: ["Imports"]
---

# Preview a roster + schedule import

`POST /api/v1/imports/preview`

## Request

- Base URL: `https://volunteerreminder.com`
- URL: `https://volunteerreminder.com/api/v1/imports/preview`
- Auth: HTTP bearer

PURE parse of a pasted CSV/table. Creates nothing. Returns the contacts, schedules, upcoming shifts, and a preview_token that a subsequent POST /imports must send back. Test-mode accounts only; account 3 is refused even in test. Does not change reminder mode. Requires `read`. Text that is UTF-16 (Excel "Unicode Text") read as UTF-8 or Latin-1 is refused with 400 `unsupported_encoding`; send CSV UTF-8 text.

## Request body

- RosterImportPreviewRequest
  - `text` string, required: CSV, TSV, pipe-delimited, or a headerless table. Recognized columns: name, phone, email, job/role, day, date, start, end. Header aliases (volunteer, weekday, from, …) are accepted. Max ~500 data rows.

## Response `200`

Parsed preview. `ok` is false when nothing usable was found.

- RosterImportPreview
  - `ok` boolean, required
  - `contacts` object[], required
    - `key` string, required
    - `full_name` string, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `email_address` string, nullable, required
    - `mobile_phone` string, nullable, required
  - `schedules` object[], required
    - `key` string, required
    - `description` string, required
    - `job_name` string, required
    - `schedule_type` 'weekly' | 'custom', required
    - `days_of_week` string[], required
    - `custom_dates` string[], required
    - `time` string, nullable, required
    - `end_time` string, nullable, required
    - `notes` string, nullable, required
    - `contact_keys` string[], required
    - `upcoming` object[], required
      - `date` string, required
      - `label` string, required
  - `assignments` object[], required
    - `schedule_key` string, required
    - `contact_keys` string[], required
  - `row_count` number, required
  - `skipped_row_count` number, required
  - `errors` object[], required
    - `line` number, required
    - `message` string, required
  - `warnings` object[], required
    - `line` number, required
    - `message` string, required
  - `reminder_mode` 'test' | 'live', required
  - `reminder_mode_note` string, required
  - `preview_token` string, required

## Other responses

- `400`: The request failed schema validation (`validation_error`). On the import endpoints, also when the text is UTF-16 (Excel "Unicode Text"; `unsupported_encoding`): resend it as CSV UTF-8.
- `401`: Missing or invalid API key.
- `403`: The API key lacks a scope required by this endpoint.
- `404`: The requested resource does not exist.

---

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