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.
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;