Petitions API

Use the Petitions API to create and interact with petitions on a site in NationBuilder.

Index Endpoint

Use this endpoint to list the petitions stored in the nation. Note that a petition requires an associated petition page to be created, the page and petition have a 1:1 relationship.

GET /api/v1/sites/:site_slug/pages/petitions

Parameters

limit - max number of results to show per page
__nonce - generated pagination nonce. Do not modify.
__token - generated pagination token. Do not modify.

Example

If you make a request like this:

GET https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions

Then you should get a 200 response with a body like this:

{
  "results": [
    {
      "id": 1,
      "slug": "my_petition",
      "path": "/my_petition",
      "status": "unlisted",
      "site_slug": "foobar-site",
      "name": "My Petition",
      "headline": "My Petition",
      "title": "My Petition - Foobar Inc.",
      "excerpt": null,
      "author_id": 2,
      "published_at": null,
      "external_id": null,
      "tags": [],
      "intro": null,
      "content": null,
      "goal": 0,
      "petition_page_slug": null,
      "additional_signatures_count": 0,
      "signature_name": "signature",
      "petition_form": {
        "phone": "hidden",
        "address": "optional",
        "gather_volunteers": true
      },
      "autoresponse": {
        "broadcaster_id": 1,
        "subject": "Thank you for signing",
        "body": null
      }
    }
  ],
  "next": null,
  "prev": null
}

Create Endpoint

Use this endpoint to create a Petition

POST /api/v1/sites/:site_slug/pages/petitions

Parameters

petition - the petition resource you wish to create

Example

POST https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions

With attached body like this:

{
  "petition": {
    "slug": "my_new_petition",
    "path": "/my_new_petition",
    "status": "unlisted",
    "name": "My New Petition",
    "headline": "My New Petition",
    "title": "My New Petition - Foobar Inc.",
    "excerpt": null,
    "author_id": 2,
    "published_at": null,
    "external_id": null,
    "tags": [],
    "intro": null,
    "content": null,
    "goal": 0,
    "petition_page_slug": null,
    "additional_signatures_count": 0,
    "signature_name": "signature",
    "petition_form": {
      "phone": "hidden",
      "address": "optional",
      "gather_volunteers": true
    },
    "autoresponse": {
      "broadcaster_id": 1,
      "subject": "Thank you for signing our new petition",
      "body": null
    }
  }
}

Then you should get a 200 response with a body like this:

{
  "petition_resource": {
    "id": 3,
    "slug": "my_new_petition",
    "path": "/my_new_petition",
    "status": "unlisted",
    "site_slug": "foobar-site",
    "name": "My New Petition",
    "headline": "My New Petition",
    "title": "My New Petition - Foobar Inc.",
    "excerpt": null,
    "author_id": 2,
    "published_at": null,
    "external_id": null,
    "tags": [],
    "intro": null,
    "content": null,
    "goal": 0,
    "petition_page_slug": null,
    "additional_signatures_count": 0,
    "signature_name": "signature",
    "petition_form": {
      "phone": "hidden",
      "address": "optional",
      "gather_volunteers": true
    },
    "autoresponse": {
      "broadcaster_id": 1,
      "subject": "Thank you for signing our new petition",
      "body": null
    }
  }
}

Update Endpoint

Use the update endpoint to change the details of a pre-existing petition page.

Show Endpoint

Get the details of a specific petition.

GET /api/v1/sites/:site_slug/pages/petitions/:id

Example

GET https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions/1

Then you should get a 200 response with a body like this:

{
  "petition_resource": {
    "id": 1,
    "slug": "my_petition",
    "path": "/my_petition",
    "status": "unlisted",
    "site_slug": "foobar-site",
    "name": "My Petition",
    "headline": "My Petition",
    "title": "My Petition - Foobar Inc.",
    "excerpt": null,
    "author_id": 2,
    "published_at": null,
    "external_id": null,
    "tags": [],
    "intro": null,
    "content": null,
    "goal": 0,
    "petition_page_slug": null,
    "additional_signatures_count": 0,
    "signature_name": "signature",
    "petition_form": {
      "phone": "hidden",
      "address": "optional",
      "gather_volunteers": true
    },
    "autoresponse": {
      "broadcaster_id": 1,
      "subject": "Thank you for signing",
      "body": null
    }
  }
}

Delete Endpoint

Remove a petition from a site.

DELETE /api/v1/sites/:site_slug/pages/petitions/:id

Signature Index Endpoint

Use this endpoint to list the signatures for a petition

GET /api/v1/sites/:site_slug/pages/petitions/:petition_id/signatures

Parameters

limit - max number of results to show per page (optional, default 10, max 100).
__nonce - generated pagination nonce. Do not modify.
__token - generated pagination token. Do not modify.

Example

Issuing this request:

GET https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions/1/signatures

Then you should get a 200 response with a body like this:

{
  "results": [
  {
    "id": 2,
    "person_id": 4,
    "person_email": "[email protected]",
    "person_first_name": "Jane",
    "person_last_name": "Doe",
    "petition_page_id": 1,
    "petition_page_slug": "my_petition",
    "site_id": 1,
    "site_slug": "foobar-site",
    "comment": "",
    "private": false,
    "recruiter_id": null,
    "created_at": "2022-03-29T11:36:46+01:00",
    "updated_at": "2022-03-29T11:36:46+01:00"
  },
  {
    "id": 1,
    "person_id": 3,
    "person_email": "[email protected]",
    "person_first_name": "Joe",
    "person_last_name": "Bloggs",
    "petition_page_id": 1,
    "petition_page_slug": "my_petition",
    "site_id": 1,
    "site_slug": "foobar-site",
    "comment": "",
    "private": false,
    "recruiter_id": null,
    "created_at": "2022-03-29T11:36:28+01:00",
    "updated_at": "2022-03-29T11:36:28+01:00"
    }
  ],
  "next": null,
  "prev": null
}

Signature Creation Endpoint

Use this endpoint to create a signature for a petition

POST /api/v1/sites/:site_slug/pages/petitions/:petition_id/signatures

Parameters

person_id - id of the person signing the petition

Example

Issuing a request like this:

POST https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions/1/signatures

With attached body like this:

{
  "signature": {
    "person_id": 2,
    "comment": "Optional comment on this submission",
    "private": false,
    "recruiter_id": null
  }
}

Then you should get a 200 response with a body like this:

{
  "signature_resource": {
    "id": 20,
    "person_id": 2,
    "person_email": "[email protected]",
    "person_first_name": "Joe",
    "person_last_name": "Bloggs",
    "petition_page_id": 1,
    "petition_page_slug": "my_petition",
    "site_id": 1,
    "site_slug": "foobar-site",
    "comment": "Optional comment on this submission",
    "private": false,
    "recruiter_id": null,
    "created_at": "2022-04-12T14:03:07+01:00",
    "updated_at": "2022-04-12T14:03:07+01:00"
  }
}

Signature Update Endpoint

Use the update endpoint to change the details of a pre-existing petition signature.

PUT /api/v1/sites/:site_slug/pages/petitions/:petition_id/signatures/:id

Signature Show Endpoint

Get the details of a specific signature.

GET /api/v1/sites/:site_slug/pages/petitions/:petition_id/signatures/:id

Example

GET https://foobar.nationbuilder.com/api/v1/sites/foobar-site/pages/petitions/1/signatures/20

Then you should get a 200 response with a body like this:

{
  "signature_resource": {
    "id": 20,
    "person_id": 2,
    "person_email": "[email protected]",
    "person_first_name": "Joe",
    "person_last_name": "Bloggs",
    "petition_page_id": 1,
    "petition_page_slug": "my_petition",
    "site_id": 1,
    "site_slug": "foobar-site",
    "comment": "Optional comment on this submission",
    "private": false,
    "recruiter_id": null,
    "created_at": "2022-04-12T14:03:07+01:00",
    "updated_at": "2022-04-12T14:03:07+01:00"
  }
}

Signature Delete Endpoint

Remove a signature from a petition.

DELETE /api/v1/sites/:site_slug/pages/petitions/:petition_id/signatures/:id