My Developer Account

FormSubmission

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 — see the FormSubmissionValue vertex for details.

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.

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.

Example Request 

curl https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions

View in API Explorer →

Example Object 

{
  "type": "FormSubmission",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "requires_verification": true,
    "selected_options_by_field": {},
    "updated_at": "2000-01-01T12:00:00Z",
    "verified": true
  },
  "relationships": {
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "form": {
      "data": {
        "type": "Form",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
created_at date_time
id primary_key
requires_verification boolean

Only available when requested with the ?fields param
selected_options_by_field json

Only available when requested with the ?fields param
updated_at date_time
verified boolean

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

Name Type Association Type Note
person Person to_one
form Form to_one

Can Include

Parameter Value Description Assignable
include form

include associated form

 create and update
include form_fields

include associated form_fields
include form_submission_values

include associated formsubmissionvalues

 create and update
include person

include associated person

 create and update

Order By

Parameter Value Type Description
order created_at string

prefix with a hyphen (-created_at) to reverse the order
order person.first_name string

prefix with a hyphen (-person.first_name) to reverse the order
order person.last_name string

prefix with a hyphen (-person.last_name) to reverse the order
order updated_at string

prefix with a hyphen (-updated_at) to reverse the order

Query By

Name Parameter Type Description Example
created_at where[created_at] date_time

Query on a specific created_at

 ?where[created_at]=2000-01-01T12:00:00Z
updated_at where[updated_at] date_time

Query on a specific updated_at

 ?where[updated_at]=2000-01-01T12:00:00Z

Pagination

Name Parameter Type Description
per_page per_page integer

how many records to return per page (min=1, max=100, default=25)
offset offset integer

get results from given offset

Endpoints

Listing

HTTP Method Endpoint
GET /people/v2/forms/{form_id}/form_submissions

Reading

HTTP Method Endpoint
GET /people/v2/forms/{form_id}/form_submissions/{id}

Creating

HTTP Method Endpoint Assignable Attributes
POST /people/v2/forms/{form_id}/form_submissions
  • person_id

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions/{form_submission_id}/form Form
GET https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions/{form_submission_id}/form_fields FormField
GET https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions/{form_submission_id}/form_submission_values FormSubmissionValue
GET https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions/{form_submission_id}/person Person

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/people/v2/forms/{form_id}/form_submissions Form