Petitions Version 1
This document describes the OSDI petitions collection and petition resource as implemented by the Action Network.
Petitions are a type of action created by the organizer or group associated with your API key that involves activists signing a common letter directed towards a target.
Petitions have summaries (titles) and can have descriptions and targets and other fields, and when activists sign them signature resources are created representing the signature an activist made on that petition.
Petitions are not deduplicated except on identifiers, to keep identifiers unique.
Sections:
- Endpoints and URL structures
- Field names and descriptions
- Links
- Scenario: Retrieving a collection of petition resources (GET)
- Scenario: Retrieving an individual petition resource (GET)
- Scenario: Creating a new petition (POST)
- Scenario: Modifying a petition (PUT)
- Scenario: Deleting a petition (DELETE)
Endpoints and URL structures
Endpoints:
https://actionnetwork.org/api/v1/petitions
Petition resources live exclusively at the above endpoint. The endpoint returns a collection of all the petitions associated with your API key.
URL Structures:
https://actionnetwork.org/api/v1/petitions/[id]
To address a specific petition, use the identifier without the action_network:
prefix to construct a URL, like https://actionnetwork.org/api/v1/petitions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3
Field names and descriptions
Field Name | Type | Required on POST | Description |
---|---|---|---|
identifiers | array[] |
An array of identifiers in the format [system name]:[id] . See the general concepts document for more information about identifiers.
|
|
originating_system | string | Yes | A human readable string identifying where this petition originated. May be used in the user interface for this purpose. |
created_at | datetime | The date and time the resource was created. System generated, not editable. | |
modified_at | datetime | The date and time the resource was last modified. System generated, not editable. | |
summary | string | Yes | The petition's title. |
description | string | The petition's description. May contain HTML. | |
petition_text | string | The letter to the petition's target. | |
url | string | The URL to this petition on the Action Network. Only present for petitions created with our user interface. Not editable. | |
total_signatures | integer | A system generated count of the number of signatures on this petition. Not editable. | |
target | target[] | An array of targets for this petition. | |
target.name | string | The name of the target. | |
osdi:creator* | osdi:person | An embedded person representing the user who created this petition. If you do not assign a creator, we will assign one based on your API key. Cannot be edited once created. | |
action_network:sponsor | hash | A hash of the sponsoring group of this petition. Action Network-only feature. Automatically added if you post using a group API key. System generated, not editable. | |
action_network:sponsor.summary | string | The name of the sponsoring group. | |
action_network:sponsor.url | string | The URL to the group's public page. |
Links
Link Name | Description |
---|---|
self | A link to this individual petition resource. |
osdi:signatures | A link to a collection of all signature resources associated with this petition. Click here for signatures documentation. |
osdi:creator | A link to the person who created this petition. Click here for people documentation. |
action_network:embed | A link to embed code for this petition. Action Network-only feature. Click here for embed documentation. |
Scenario: Retrieving a collection of petition resources (GET)
Petition resources are sometimes presented as collections of petitions. For example, calling the petitions endpoint will return a collection of all the petitions associated with your API key.
Request
GET https://actionnetwork.org/api/v1/petitions/
Header:
api-key:[your api key here]
Response
Back To Top ↑200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate
{ "total_pages": 7, "per_page": 25, "page": 1, "total_records": 162, "_links": { "next": { "href": "https://actionnetwork.org/api/v1/petitions?page=2" }, "self": { "href": "https://actionnetwork.org/api/v1/petitions" }, "osdi:petitions": [ { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d" }, { "href": "https://actionnetwork.org/api/v1/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3" }, //truncated for brevity ], "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] }, "_embedded": { "osdi:petitions": [ { "identifiers": [ "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d" ], "originating_system": "Action Network", "created_at": "2014-03-24T18:03:45Z", "modified_at": "2014-03-25T15:00:22Z", "summary": "Stop doing the bad thing", "description": "<p>The mayor should stop doing the bad.</p>", "petition_text": "Mayor, stop doing the bad thing", "url": "https://actionnetwork.org/petitions/stop-doing-the-bad-thing", "total_signatures": 2354, "target": [ { "name": "The Mayor" } ], "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "originating_system": "Action Network", "created_at": "2014-03-24T18:03:45Z", "modified_at": "2014-03-25T15:00:22Z", "email_addresses": [ { "primary": true, "address": "jdoe@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 35.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" } } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/embed" } } }, { "identifiers": [ "action_network:a27178b9-45c3-4844-8ebf-ebd5da74a1e3", "foreign_system:1" ], "originating_system": "Another System", "created_at": "2014-03-14T15:21:05Z", "modified_at": "2014-03-17T19:56:11Z", "summary": "We need to do this now!", "total_signatures": 123, "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "originating_system": "Action Network", "created_at": "2014-03-24T18:03:45Z", "modified_at": "2014-03-25T15:00:22Z", "email_addresses": [ { "primary": true, "address": "jdoe@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 35.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" } } } }, "action_network:sponsor": { "summary": "Progressive Action Now", "url": "https://actionnetwork.org/groups/progressive-action-now" }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/embed" } } }, //truncated for brevity ] } }
Scenario: Retrieving an individual petition resource (GET)
Calling an individual petition resource will return the resource directly, along with all associated fields and appropriate links to additional information about the petition.
Request
GET https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d
Header:
api-key:[your api key here]
Response
Back To Top ↑200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate
{ "identifiers": [ "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d" ], "originating_system": "Action Network", "created_at": "2014-03-24T18:03:45Z", "modified_at": "2014-03-25T15:00:22Z", "summary": "Stop doing the bad thing", "description": "<p>The mayor should stop doing the bad.</p>", "petition_text": "Mayor, stop doing the bad thing", "url": "https://actionnetwork.org/petitions/stop-doing-the-bad-thing", "total_signatures": 2354, "target": [ { "name": "The Mayor" } ], "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "originating_system": "Action Network", "created_at": "2014-03-24T18:03:45Z", "modified_at": "2014-03-25T15:00:22Z", "email_addresses": [ { "primary": true, "address": "jdoe@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 35.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
Scenario: Creating a new petition (POST)
You can post a new petition to the petitions endpoint and a petition resource will be created in our system.
Note: Petitions created via the API in this way are not equivalent to petitions created with our user interface. API-created petitions will not show up in lists of all of your actions on your dashboard of group page, they will not be given a URL on actionnetwork.org where people can sign, and they will not have individual manage pages for statistics and delivery. Rather, once they have at least one signature, they will show up as actions available for selection in our targeting interface, allowing you to select all people who have taken action on that petition for reports or email targeting.
In the targeting interface, they will show up in the format [1, (originating system) Petition], (summary)
. For example, a petition with the originating system "FreePetitions.com" and the summary "My Free Petition" will show up in the targeting interface as [1, FreePetitions.com Petition], My Free Petition
so you can easily identify what it is and where it came from when doing your targeting.
Request
POST https://actionnetwork.org/api/v1/petitions Header: Content-Type: application/json api-key:[your api key here]
{ "identifiers": [ "free_petitions:1" ], "summary": "My Free Petition", "originating_system": "FreePetitions.com" }
Response
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate
{ "identifiers": [ "free_petitions:1", "action_network:9f837109-710d-442f-8a99-857a21f36d25" ], "created_at": "2014-03-26T15:26:30Z", "modified_at": "2014-03-26T15:26:30Z", "summary": "My Free Petition", "total_signatures": 0, "originating_system": "FreePetitions.com", "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "originating_system": "Action Network", "created_at": "2014-03-20T21:04:31Z", "modified_at": "2014-03-20T21:04:31Z", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "email_addresses": [ { "primary": true, "address": "jdoe@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave" ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 32.249, "longitude": -73.0339, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } } }, "_links": { "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "self": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
In the above example, you can see how the foreign identifier being posted is merged into the identifiers array. We will intelligently search and deduplicate based on foreign and native identifiers. So if you post a petition with an identifier that matches one already assigned to a petition resource, your POST request will update that resource with new information instead of creating a duplicate.
You can post a petition with a creator link as well, if you want to assign the petition to a specific Action Network user, like so:
POST https://actionnetwork.org/api/v1/petitions Header: Content-Type: application/json api-key:[your api key here]
{ "identifiers": [ "free_petitions:1" ], "summary": "My Free Petition", "originating_system": "FreePetitions.com", "_links" : { "osdi:creator" : { "href" : "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" } } }
The link must be a valid person resource and must be associated with your API key for it to be accepted. If your API key is for an individual account, then the link must be to your account's person resource. If your API key is for a group, then the link must be to a member of administrator of your group. If no link or an invalid link is provided, the petition will be assigned to your API key's account person record or to the original creator of the group, whichever is appropriate. If a creator is explicitly set, people who take action will be added to that creator's personal email list. Otherwise, the creator is has no effect on what email list people who sign the petition are subscribed to.
And of course you can post a petition with more fields (such as description) if you'd like, but they are not required.
Back To Top ↑Scenario: Modifying a petition (PUT)
You can modify an existing petition by using PUT on its individual endpoint.
Request
PUT https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25 Header: Content-Type: application/json api-key:[your api key here]
{ "identifiers": [ "free_petitions:2" ], "summary": "My Free Petition With A New Name", "description": "This is my free petition description" }
Response
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate
{ "identifiers": [ "free_petitions:1", "action_network:9f837109-710d-442f-8a99-857a21f36d25", "free_petitions:2" ], "created_at": "2014-03-26T15:26:30Z", "modified_at": "2014-03-26T15:39:48Z", "summary": "My Free Petition With A New Name", "description": "This is my free petition description", "total_signatures": 0, "originating_system": "FreePetitions.com", "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "originating_system": "Action Network", "created_at": "2014-03-20T21:04:31Z", "modified_at": "2014-03-20T21:04:31Z", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "email_addresses": [ { "primary": true, "address": "jdoe@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave" ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 32.249, "longitude": -73.0339, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
The above example added a new identifier to the petition, changed the summary, and added a description.
Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the total_signatures count -- that is a system generated number reflecting a count of the underlying signatures. And you can't change a creator of a petition. Invalid entries will be ignored.
Back To Top ↑Scenario: Deleting a petition (DELETE)
Deleting petitions is not allowed via the API. DELETE requests will return an error.
Back To Top ↑