---
title: "Add volunteers in bulk"
method: POST
path: "/api/v1/contacts/bulk"
tags: ["Contacts"]
---

# Add volunteers in bulk

`POST /api/v1/contacts/bulk`

## Request

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

Add up to 200 contacts in one call. ALL-OR-NOTHING: if the batch would push the account's active-volunteer count past its plan's limit, or any contact references a `group_id` that doesn't belong to this account, NOTHING is created and a `validation_error` names the limit, the account's current count, or the bad group id. Requires `contacts:write`.

## Request body

- BulkCreateContactsRequest
  - `consent_attested` boolean: Required to be `true` when any contact in this request has a `mobile_phone`. 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." The affirmation is recorded with your API key id and the time, and is what we produce if a carrier audits our messaging. Omit for email-only contacts.
  - `contacts` ContactFields[], required: Contacts to add, up to 200 per request.
    - `full_name` string, required: Display name, shown on the roster and in reminder text. Required.
    - `first_name` string, nullable: First name, or `null`/omit if not recorded separately.
    - `last_name` string, nullable: Last name, or `null`/omit if not recorded separately.
    - `email_address` string, email, nullable: Email address reminders may be sent to, or `null`/omit.
    - `mobile_phone` string, nullable: Mobile phone number, used for SMS reminders. Accepts E.164 (`+15125550100`) or a plain 10-digit US/Canada number; normalized to E.164 on save. Send `null` or `""` to clear it.
    - `land_phone` string, nullable: Landline phone number (not SMS-capable, informational only), or `null`/omit.
    - `group_id` integer, nullable: Id of an existing group on this account to file the contact under, or `null` for no group. Must reference a group already owned by this account.
    - `notes` string, nullable: Free-text notes about the contact.

## Response `201`

The created contacts.

- BulkCreateContactsResponse
  - `created` Contact[], required: The newly created contacts, in the same order as submitted.
    - `id` number, required: Contact id.
    - `full_name` string, required: Display name, shown on the roster and in reminder text.
    - `first_name` string, nullable, required: First name, or `null` if not recorded separately.
    - `last_name` string, nullable, required: Last name, or `null` if not recorded separately.
    - `email_address` string, nullable, required: Email address reminders may be sent to, or `null`.
    - `mobile_phone` string, nullable, required: Mobile phone in E.164 format, used for SMS reminders, or `null`.
    - `land_phone` string, nullable, required: Landline phone number (not SMS-capable, informational only), or `null`.
    - `group_id` number, nullable, required: Id of the group this contact belongs to, or `null`.
    - `group_name` string, nullable, required: Display name of the group, or `null` when ungrouped.
    - `notes` string, nullable, required: Free-text notes about the contact, or `null`.
    - `created_at` number, required: Epoch milliseconds (UTC) the contact was created.

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