Skip to content

FormSubmissionValue (People)

A single answer to a single field within a form submission.

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 FormFieldOption id as a string, not the option’s text. A checkboxes or workflow_checkboxes field takes one included FormSubmissionValue per selected option. To answer the field’s Other option, send { "other": "…" } instead. For the workflow_* types, submitting the answer creates a WorkflowCard in the linked workflow.
  • phone_number: an object like { "number": "555-555-1234", "location": "Mobile" }. location defaults to "Mobile" when omitted.
  • address: an object like { "location": "Home", "street": "123 Main St", "city": "Carlsbad", "state": "CA", "zip": "92008", "country_code": "US" }. location defaults to "Home" when omitted. street is a single string, not the street_line_1/street_line_2 pair the Address resource uses; put \n before a second line. country_code is an uppercase ISO 3166-1 alpha-2 code. When the field is required, every property except location must be filled in.
  • file: an array of { "fileID": "us4-…", "fileName": "waiver.pdf" } objects. Each object must have exactly those two keys and no others. fileID is the full id returned by the upload service, including its datacenter prefix (see “Uploading files” above). Single-file fields accept one object; fields whose settings.multiple_files is true accept up to 5. Each file may be at most 10 MB, and common executable and script file types are rejected. The fileName key is required, but its value is ignored: the stored file keeps the name it was uploaded with.
  • custom_field: follows the linked FieldDefinition’s data_type — usually a string, or the file array above when data_type is file.

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;

Type to search…

↑↓ navigate↵ selectEsc close