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

# Import a roster + schedule

`POST /api/v1/imports`

## Request

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

Parse a pasted CSV/table and create contacts, weekly/custom schedules, and roster assignments. Requires preview_token from POST /imports/preview for the same text. Test-mode accounts only; account 3 is refused even in test. Does not change reminder mode, the confirm loop, or the substitute finder. Requires `schedules:write` and `contacts:write`. UTF-16 text is refused with 400 `unsupported_encoding`, as on preview.

## Request body

- RosterImportCommitRequest
  - `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.
  - `consent_attested` boolean: Required to be `true` on commit when any imported contact has a mobile number. By setting it you affirm: "I confirm these volunteers gave their mobile number to our organization and agreed to receive shift reminder texts from us, sent through VolunteerReminder, and that I can show how they agreed if asked." Omit on preview, or when every contact is email-only.
  - `preview_token` string: Required on commit. Copy the preview_token from POST /api/v1/imports/preview for this exact roster text. Optional in the schema so a live or blocked account still receives 403 (not 400) when the token is omitted.

## Response `201`

Created contacts, schedules, and assignments.

- RosterImportCommit
  - `contacts_created` number, required
  - `schedules_created` number, required
  - `assignments_created` number, required
  - `contacts` object[], required
    - `id` number, required
    - `key` string, required
    - `full_name` string, required
  - `schedules` object[], required
    - `id` number, required
    - `key` string, required
    - `description` string, required
    - `contact_ids` number[], required
    - `upcoming` object[], required
      - `date` string, required
      - `label` string, 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

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