---
title: "Create a petition"
method: POST
path: "/api/v2/petitions"
tags: ["Petitions"]
---

# Create a petition

`POST /api/v2/petitions`

## Request

- Base URL: `https://yournation.nationbuilder.com`
- URL: `https://yournation.nationbuilder.com/api/v2/petitions`
- Auth: HTTP bearer

Creates a petition from given data

## Request body

- PetitionCreateRequest: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
  - `data` object, required
    - `type` 'petitions', required: The JSON:API resource type of the resource being created.
    - `attributes` PetitionReadWriteAttributes: The attributes of a petition that can be both read and written.
      - `additional_signatures_count` integer, nullable: Number of offline signatures to add to the signature count total.
      - `auto_response_broadcaster_id` string, nullable: The broadcaster that sends the autoresponse.
      - `auto_response_content` string, nullable: The content of the autoresponse email.
      - `auto_response_subject` string, nullable: The subject in the autoresponse email.
      - `content` string, nullable: The content is rendered on the petition page.
      - `gather_volunteers` boolean, nullable: Ask for signers to volunteer.
      - `goal` integer, nullable: The number of signatures you want this petition to receive.
      - `intro` string, nullable: The intro is rendered on the petition page above the content.
      - `is_auto_response` boolean, nullable: Sends an autoresponse to a signup after signing the petition.
      - `page_id` string, nullable: ID of the page associated with the petition
      - `petition_form_address` 'required' | 'optional' | 'hidden' | 'null', nullable: Require or ask signers to include their address in the signature.
      - `petition_form_phone` 'required' | 'optional' | 'hidden' | 'null', nullable: Require or ask signers to include their phone number in the signature.
      - `signature_name` string, nullable: What you call a signature.
    - `relationships` object
      - `page` object
        - `data` object: Identifies a related resource written in the same request (a sidepost), an extension to JSON:API. For method create, the temp-id links this relationship entry to the matching object in the request's top-level included array; the other methods identify an existing related resource by id. Omitting method associates an existing resource without modifying it.
          - `type` 'pages', required: The JSON:API type of the related resource.
          - `id` string: The ID of an existing related resource; used with every method except create.
          - `temp-id` string: Client-generated temporary ID tying this relationship to an entry in the included array when creating the related resource.
          - `method` 'create' | 'update' | 'destroy' | 'disassociate': The sidepost operation to perform on the related resource.
  - `included` object[]
    - `type` 'pages'
    - `temp-id` string
    - `attributes` object: Writable page attributes for sideposting; excludes page_type_name which the parent resource sets.
      - `author_id` string, nullable: The author of the page.
      - `excerpt` string, nullable: Longer page description used for search engine optimization.
      - `external_id` string, nullable: Optional reference for pages imported from an external service.
      - `headline` string, nullable: This is a header rendered above the page content.
      - `name` string: The name of the page.
      - `parent_id` string, nullable: The parent page ID (null for top-level pages).
      - `permission_level` 'anyone' | 'logged_in' | 'members' | 'control_panel_users' | 'admins': The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only).
      - `site_id` string: The site this page belongs to.
      - `slug` string: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
      - `status` 'archived' | 'deleted' | 'expired' | 'hidden' | 'published' | 'rule_violated' | 'unlisted': The page status - describing the visibility of the page.
      - `title` string: Brief page description seen on search engines.
      - `page_type_name` 'Petition': Must be 'Petition' since this page is being created for the petition.

## Response `201`

The newly created petition.

- PetitionShowResponseWithRequiredSidepost: The JSON:API top-level document shape for responses returning a single resource under the data member.
  - `data` object, required: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
    - `id` string, required: Unique identifier of the resource.
    - `type` 'petitions', required: The JSON:API resource type.
    - `attributes` PetitionReadWriteAttributes: The attributes of a petition that can be both read and written.
      - `additional_signatures_count` integer, nullable: Number of offline signatures to add to the signature count total.
      - `auto_response_broadcaster_id` string, nullable: The broadcaster that sends the autoresponse.
      - `auto_response_content` string, nullable: The content of the autoresponse email.
      - `auto_response_subject` string, nullable: The subject in the autoresponse email.
      - `content` string, nullable: The content is rendered on the petition page.
      - `gather_volunteers` boolean, nullable: Ask for signers to volunteer.
      - `goal` integer, nullable: The number of signatures you want this petition to receive.
      - `intro` string, nullable: The intro is rendered on the petition page above the content.
      - `is_auto_response` boolean, nullable: Sends an autoresponse to a signup after signing the petition.
      - `page_id` string, nullable: ID of the page associated with the petition
      - `petition_form_address` 'required' | 'optional' | 'hidden' | 'null', nullable: Require or ask signers to include their address in the signature.
      - `petition_form_phone` 'required' | 'optional' | 'hidden' | 'null', nullable: Require or ask signers to include their phone number in the signature.
      - `signature_name` string, nullable: What you call a signature.
  - `included` object[]: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
    - `id` string, required: Unique identifier of the resource.
    - `type` 'pages', required: The JSON:API resource type.
    - `attributes` object: The read-only attributes of a page.
      - `author_id` string, nullable: The author of the page.
      - `excerpt` string, nullable: Longer page description used for search engine optimization.
      - `external_id` string, nullable: Optional reference for pages imported from an external service.
      - `headline` string, nullable: This is a header rendered above the page content.
      - `name` string: The name of the page.
      - `parent_id` string, nullable: The parent page ID (null for top-level pages).
      - `permission_level` 'anyone' | 'logged_in' | 'members' | 'control_panel_users' | 'admins': The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only).
      - `site_id` string: The site this page belongs to.
      - `slug` string: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
      - `status` 'archived' | 'deleted' | 'expired' | 'hidden' | 'published' | 'rule_violated' | 'unlisted': The page status - describing the visibility of the page.
      - `title` string: Brief page description seen on search engines.
      - `ancestors_permission_level` string, nullable: The most restrictive permission level inherited from parent pages in the hierarchy. Returns null if the page has no parent.
      - `effective_permission_level` string: The actual permission level that will be enforced for this page. This is the most restrictive level between the page itself and its ancestors, ensuring users need the highest required access level to view the page.
      - `parent_slug` string, nullable: The parent page slug (null for top-level pages).
      - `published_at` string, date-time, nullable: When this page was published.
      - `url_path` string: URL to the page.
      - `page_type_name` 'Petition': Must be 'Petition' since this is the page associated with the petition.
    - `relationships` object: References from this resource to other resources in the document.
    - `temp-id` string
  - `meta` object: Non-standard information about the document. Empty unless the endpoint has metadata to convey.

## Other responses

- `400`: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload.
- `401`: The access token is missing, expired, or not authorized to access this resource.
- `422`: Model validations failed for the resource being created or updated. Unlike this API's other errors, validation failures are returned as a JSON:API errors document locating each invalid field.
- `429`: The access token has exceeded its request quota for the current rate-limit window.

## Changes

- **2026-11-05** `d5c88ca497ac`: 4 breaking, 3 warning, 7 info
  - added `#/components/schemas/create_request_document, subschema #2` to the request body `allOf` list
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `201`
  - removed the required property `data` from the response with the `201` status
  - …10 more
- **2026-02-14** `31995b0a1e61`: 5 breaking, 1 warning, 21 info
  - the request property `included/items/attributes/name` became not nullable
  - the request property `included/items/attributes/page_type_name` became not nullable
  - the request property `included/items/attributes/slug` became not nullable
  - the request property `included/items/attributes/title` became not nullable
  - …23 more

[Operation history](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/changes/api/v2/petitions/post.md)

---

[API](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api.md) - [All operations](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/revisions/d5c88ca497ac?raw)