---
title: "Add a volunteer"
method: POST
path: "/api/v1/contacts"
tags: ["Contacts"]
---

# Add a volunteer

`POST /api/v1/contacts`

## Request

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

Add one contact to the roster. Blocked with `validation_error` when the account is already at its plan's volunteer limit (domain/volunteerCap.ts, the same rule the dashboard enforces). Requires `contacts:write`.

## Request body

- ContactCreateRequest
  - `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.
  - `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.

## Response `201`

The created contact.

- Contact
  - `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)