---
title: "FormSubmission (People)"
description: "A form submission represents a single completed entry submitted through a Planning Center form."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FormSubmission (People)

A form submission represents a single completed entry submitted through a Planning Center form.

**Creating submissions**

`POST` is supported so external integrations can record submissions captured outside of Church Center — for example, paper forms run through OCR. Creating a submission requires the access token to belong to a user who (1) has overall People permissions of Editor or above and (2) can manage the target form (a Manager, or a user with a `manage` `FormShare`).

**Identifying the submitter**

Provide either `person_id` (an existing person in your organization) or `person_attributes`. When `person_attributes` is supplied, the API matches against existing profiles by first name (or given name or nickname) + last name + email address. If no match is found, a new person is created automatically.

`person_attributes` accepts `first_name`, `last_name`, and `emails_attributes` (an array with at least one `{ "location": "...", "address": "..." }` hash).

**Form values**

Pass each answer as an `included` resource of type `FormSubmissionValue`, with `form_field_id` referencing a field on the form. The shape of `value` depends on the field's `field_type`: plain fields take a string, phone and address fields take an object, and file fields take an array of uploaded file references. See the `FormSubmissionValue` vertex for the full list of shapes and for how to upload files.

```text
{
  "data": { "attributes": { "person_id": "1" } },
  "included": [
    { "type": "FormSubmissionValue", "attributes": { "form_field_id": "10", "value": "Blue" } },
    { "type": "FormSubmissionValue", "attributes": { "form_field_id": "11", "value": { "number": "555-555-1234", "location": "Mobile" } } },
    { "type": "FormSubmissionValue", "attributes": { "form_field_id": "12", "value": { "location": "Home", "street": "123 Main St", "city": "Carlsbad", "state": "CA", "zip": "92008", "country_code": "US" } } },
    { "type": "FormSubmissionValue", "attributes": { "form_field_id": "13", "value": [{ "fileID": "us4-2b1f6c0e-5d3a-4f7e-9c21-8a6d0e4b7f10", "fileName": "waiver.pdf" }] } }
  ]
}
```

One important note: if the form field has options (for example, a checkboxes or dropdown field), the submitted `value` should be the ID of the selected option, not the option's text.

**Side effects**

A submission triggers the same side effects as a Church Center submission: notification emails to the form's subscribers, a confirmation email to the submitter (if the form is configured to send one), workflow card creation for workflow answer fields, and profile updates for contact info, birthdate, gender, household, custom fields, and other profile data.

The access token's user is recorded as the submitter, unless they are the person the submission is for. Profile updates from the submission are attributed to that user in the person's history.

When the resolved person is brand new (created by this submission), profile updates happen immediately and the submission is auto-verified. When the resolved person already exists and the form contains verification-required fields, a verification email is sent first; profile updates apply only after the submitter clicks the verification link — matching the behavior of an unauthenticated Church Center submission.

| Property | Value |
| --- | --- |
| Product | [People](/reference/people/) (`pco.people`, API version `2026-10-05`) |
| Resource type | `FormSubmission` |
| TypeScript | `People.FormSubmission`, attributes `People.FormSubmissionAttributes`, schema `People.FormSubmissionSchema` |
| Planning Center path | `/people/v2/forms/{form_id}/form_submissions` |
| Planning Center docs | [FormSubmission](https://api.planningcenteronline.com/docs/apps/people/versions/2026-10-05/vertices/form_submission) |

## How to reach it

| Client path | Returns | Filters | Create |
| --- | --- | --- | --- |
| `pco.people.forms.id(formId).form_submissions` | Collection |  | Yes |

From a collection, `.id(formSubmissionId)` addresses one FormSubmission: `pco.people.forms.id(formId).form_submissions.id(formSubmissionId)`. Collections support [`where`, `include`, `order`, and pagination](/guides/querying/); single resources have `get()`.

## Attributes

On `People.FormSubmissionAttributes`. Every resource also has `id` and `type` (`'FormSubmission'`) next to its attributes.

| Name | Type | Description |
| --- | --- | --- |
| `created_at` | `string \| null` |  |
| `requires_verification` | `boolean \| null` | Only available when requested with the `?fields` param True if the form has fields requiring verification (contact info or household) and the submission is for an existing, untrusted person. Use `?fields[FormSubmission]=requires_verification` to opt into this attribute. |
| `selected_options_by_field` | `Record<string, unknown> \| null` | Only available when requested with the `?fields` param |
| `updated_at` | `string \| null` |  |
| `verified` | `boolean \| null` | True once the submitter has confirmed any verification-required answers. Auto-set to true when the submission creates a brand-new person; otherwise false until the submitter clicks the verification email. |

## Relationships and includes

Side-load with `include()` (or `get({ include })`) and read with `related(resource, name)`: `form`, `form_fields`, `form_submission_values`, `person`.

| Relationship | Type | To | Includable |
| --- | --- | --- | --- |
| `form` | To one | [Form](/reference/people/form/) | Yes |
| `person` | To one | [Person](/reference/people/person/) | Yes |

## Querying

### Where

`where(field, value)` for equality; `where(field, op, value)` with the operators listed.

| Field | Value type | Operators |
| --- | --- | --- |
| `created_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |
| `updated_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |

### Order

`order(...)` accepts these fields, ascending, or descending with a `-` prefix: `created_at`, `person.first_name`, `person.last_name`, `updated_at`.

## Edges

Follow these from one FormSubmission, `ref = pco.people.forms.id(formId).form_submissions.id(formSubmissionId)`:

| Edge | Leads to | Returns | Filters | Create |
| --- | --- | --- | --- | --- |
| `ref.form` | [Form](/reference/people/form/) | Collection |  | No |
| `ref.form_fields` | [FormField](/reference/people/form-field/) | Collection |  | No |
| `ref.form_submission_values` | [FormSubmissionValue](/reference/people/form-submission-value/) | Collection |  | No |
| `ref.person` | [Person](/reference/people/person/) | Collection |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `form_submissions` on [Form](/reference/people/form/) |
| Update | No |
| Delete | No |

### Create attributes

Typed as `People.FormSubmissionSchema['create']`.

| Attribute | Type |
| --- | --- |
| `person_id` | `string` |

See [Writing data](/guides/writing-data/).

## Example

```ts
import type { People } from '@mackenly/planningcenterkit';

const formId = '1'; // Form id

const page = await pco.people.forms.id(formId).form_submissions.order('created_at').perPage(25).list();
const items: People.FormSubmission[] = page.data;
```

Source: https://planningcenterkit.mackenly.com/reference/people/form-submission/index.mdx
