---
title: "FormSubmissionValue (People)"
description: "A single answer to a single field within a form submission."
---

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

# FormSubmissionValue (People)

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.

```text
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.

```text
{
  "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](/reference/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](https://api.planningcenteronline.com/docs/apps/people/versions/2026-10-05/vertices/form_submission_value) |

## 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](/guides/querying/); 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](#value). |

### Attribute details

#### `value` {#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](/reference/people/form-field/) | No |
| `form_field_option` | To one | [FormFieldOption](/reference/people/form-field-option/) | No |
| `form_submission` | To one | [FormSubmission](/reference/people/form-submission/) | 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

```ts
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;
```

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