Skip to content

FormSubmission (People)

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

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.

{
  "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 (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

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; 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 Yes
person To one 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 Collection No
ref.form_fields FormField Collection No
ref.form_submission_values FormSubmissionValue Collection No
ref.person Person Collection No

Writing

Property Value
Create Yes, create() on form_submissions on Form
Update No
Delete No

Create attributes

Typed as People.FormSubmissionSchema['create'].

Attribute Type
person_id string

See Writing data.

Example

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;

Type to search…

↑↓ navigate↵ selectEsc close