A single answer to a single field within a form submission.
When creating a FormSubmission, supply one FormSubmissionValue per answered field as a JSON:API included resource. Each must reference a form_field_id belonging to the parent form; values referencing fields on other forms are silently discarded. Blank values are also discarded.
value is write-only. It is accepted when creating a submission but is never returned when reading one. Read answers back through display_value and, for file fields, attachments.
Uploading files
File answers reference files that have already been uploaded to the Planning Center upload service. Upload each file first with a multipart POST to https://upload.planningcenteronline.com/v2/files, one file per request. The request authenticates like any other Planning Center API request: a personal access token as HTTP Basic, or an OAuth access token as a Bearer token. It does not have to be the same credential that later creates the submission.
curl -X POST https://upload.planningcenteronline.com/v2/files -u <application id>:<secret> -F "file=@waiver.pdf"The response lists the uploaded file under data. Use data[0].id as fileID and data[0].attributes.name as fileName. fileID must be sent exactly as returned, including its datacenter prefix (such as us4-).
Uploads are temporary. data[0].attributes.expires_at is 60 minutes after the upload, so create the submission soon after uploading. People copies the file into its own storage when the submission is created, and that copy is unaffected by the upload expiring.
A file answer that is malformed, lacks the prefix, or points at an expired or unknown upload fails the request with a 422 validation error on value that says which.
{
"data": { "attributes": { "person_id": "1" } },
"included": [
{
"type": "FormSubmissionValue",
"attributes": {
"form_field_id": "42",
"value": [{ "fileID": "us4-2b1f6c0e-5d3a-4f7e-9c21-8a6d0e4b7f10", "fileName": "waiver.pdf" }]
}
}
]
}| Property | Value |
|---|---|
| Product | People (pco.people, API version 2026-10-05) |
| Resource type | FormSubmissionValue |
| TypeScript | People.FormSubmissionValue, attributes People.FormSubmissionValueAttributes, schema People.FormSubmissionValueSchema |
| Planning Center path | /people/v2/forms/{form_id}/form_submissions/{form_submission_id}/form_submission_values |
| Planning Center docs | FormSubmissionValue |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.people.forms.id(formId).form_submissions.id(formSubmissionId).form_submission_values |
Collection | No |
From a collection, .id(formSubmissionValueId) addresses one FormSubmissionValue: pco.people.forms.id(formId).form_submissions.id(formSubmissionId).form_submission_values.id(formSubmissionValueId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On People.FormSubmissionValueAttributes. Every resource also has id and type ('FormSubmissionValue') next to its attributes.
| Name | Type | Description |
|---|---|---|
attachments |
unknown[] | null |
|
display_value |
string | null |
|
value |
string | null |
See details. |
Attribute details
value
Write-only. Accepted when creating a submission and never returned.
The submitted answer. The shape depends on the parent FormField’s field_type:
- string, text, number, note, medical: the literal value as a string
- date, birthday, anniversary: an ISO 8601 date as a string
- boolean:
"true"or"false" - gender, marital_status, school, primary_campus: the option’s id as a string (look up via
/people/v2/genders,/people/v2/marital_statuses,/people/v2/school_options,/people/v2/campuses) - grade: the grade number as a string, such as
"3" - checkboxes, dropdown, workflow_checkbox, workflow_checkboxes, workflow_dropdown: the
FormFieldOptionid as a string, not the option’s text. Acheckboxesorworkflow_checkboxesfield takes oneincludedFormSubmissionValueper selected option. To answer the field’s Other option, send{ "other": "…" }instead. For theworkflow_*types, submitting the answer creates aWorkflowCardin the linked workflow. - phone_number: an object like
{ "number": "555-555-1234", "location": "Mobile" }.locationdefaults to"Mobile"when omitted. - address: an object like
{ "location": "Home", "street": "123 Main St", "city": "Carlsbad", "state": "CA", "zip": "92008", "country_code": "US" }.locationdefaults to"Home"when omitted.streetis a single string, not thestreet_line_1/street_line_2pair theAddressresource uses; put\nbefore a second line.country_codeis an uppercase ISO 3166-1 alpha-2 code. When the field is required, every property exceptlocationmust be filled in. - file: an array of
{ "fileID": "us4-…", "fileName": "waiver.pdf" }objects. Each object must have exactly those two keys and no others.fileIDis the full id returned by the upload service, including its datacenter prefix (see “Uploading files” above). Single-file fields accept one object; fields whosesettings.multiple_filesis true accept up to 5. Each file may be at most 10 MB, and common executable and script file types are rejected. ThefileNamekey is required, but its value is ignored: the stored file keeps the name it was uploaded with. - custom_field: follows the linked
FieldDefinition’sdata_type— usually a string, or the file array above whendata_typeisfile.
The example value shown here is a placeholder — the real shape depends on the field’s field_type.
Relationships and includes
Planning Center documents no includes for this resource.
| Relationship | Type | To | Includable |
|---|---|---|---|
form_field |
To one | FormField | No |
form_field_option |
To one | FormFieldOption | No |
form_submission |
To one | FormSubmission | No |
Querying
No documented where fields.
No documented order fields.
Edges
This resource has no documented edges.
Writing
| Property | Value |
|---|---|
| Create | No |
| Update | No |
| Delete | No |
Example
import type { People } from '@mackenly/planningcenterkit';
const formId = '1'; // Form id
const formSubmissionId = '1'; // FormSubmission id
const page = await pco.people.forms.id(formId).form_submissions.id(formSubmissionId).form_submission_values.perPage(25).list();
const items: People.FormSubmissionValue[] = page.data;