Developers / API Documentation / Resources

Petitions

GET petitions

Returns the array of petition data objects corresponding to the petition IDs submitted. It is the same as doing GET petitions/:petition_id in bulk over an array of IDs.

Request Parameters

Parameter Name Type Description
petition_ids string of comma-separated petition IDs An array of IDs for the petitions about which information should be retrieved.

Example: "5445,29301,7762"
fields string of comma-separated field names (Optional) The fields of the petition data object that will be returned for each petition in the response. The parameter should include the field names (described in GET petitions/:petition_id), separated by commas. Omitting this parameter will return all available fields.

Example: "title,url,signature_count"
page_size int (Optional) The maximum number of petition data objects to return per request, no more than 500. If omitted, returns the maximum number of petitions.
page int (Optional) The page offset by page_size petitions. If omitted, returns the first page by default.
sort string (Optional) The order by which petitions will be returned. Accepted values are the number of signatures, signatures_asc or signatures_desc, or the date and time the petition was created, time_asc or time_desc. If omitted, returns petitions in the ascending order in which they were created.

Response Data

Field Name Type Description
page int The current page number. Will default to 1.
prev_page_endpoint string The API endpoint that can be called to retrieve the previous page of petitions. null if there is no previous page.
next_page_endpoint string The API endpoint that can be called to retrieve the next page of petitions. null if there is no next page.
page int The current page number.
total_pages int The total number of pages of petitions (of size specified by page_size)
petitions array The array of petitions (specified in GET petitions/:petition_id)

GET petitions/:petition_id

Returns information about this petition, including the overview, letter to the petition target, URL to the petition image (if available), and signature count.

Request Parameters

Parameter Name Type Description
petition_id int (In URL) The petition about which information should be retrieved.
fields string of comma-separated field names (Optional) The fields that will be returned in the response. The parameter should include the field names (described below in Response Data), separated by commas. Omitting this parameter will return all available fields.

Example: "title,url,signature_count"

Response Data

Field Name Type Description
title string The human-readable title of the petition.
status string Possible values are open, closed, and victory.
url string The URL of the petition on Change.org.
overview string The overview text of the petition.
targets array The list of targets. (See Targets on Petitions.)
letter_subject string The subject line of the petition letter to the target(s).
letter_salutation string The salutation of the petition letter to the target(s).
letter_body string The body content of the petition letter to the target(s).
signature_count int The petition's total number of signatures.
image_url string (If available) The URL to the petition's image on Change.org.
category string (If available) The category that the petition is in on Change.org.
goal int (If available) The signature goal for a petition.
created_at string of ISO-8601 datetime The date and time the petition was created.
end_at string of ISO-8601 datetime (If available) The deadline for the petition.
creator_name string (If applicable) The name of the petition creator.
creator_url string (If applicable) The URL to the Change.org profile page of the petition creator.
organization_name string (If applicable) The name of the organization that created the petition.
organization_url string (If applicable) The URL to the Change.org profile page of the organization that created the petition.

Example:

GET https://api.change.org/v1/petitions/48503
=> {
"title": "Tell Congress: Build the Enterprise",
"url": "http://www.change.org/petitions/tell-congress-build-the-enterprise",
"overview": "It's time to build the Enterprise, don't you think?",
"targets": [{
"name": "US House of Representatives",
"type": "us_government",
}],
"letter": "Dear Congress,
Please build the USS Enterprise as quickly as possible.
Thank you.",
"image_url": "https://change-production.s3.amazonaws.com/photos/1/bi/gp/fdjs.jpg",
"signature_count": 23456,
"creator_name": "Gene Roddenberry",
"creator_url": "http://www.change.org/members/382934"
}

GET petitions/get_id

Returns the unique Change.org ID for the petition specified by petition_url. Before performing requests on a petition, the unique Change.org ID is required because petition URLs can change.

Request Parameters

Parameter Name Type Description
petition_url string The petition whose ID will be retrieved.

Response Data

The ID of the requested petition.

Field Name Type Description
petition_id int The unique Change.org ID of the petition.

Example:

GET https://api.change.org/v1/petitions/get_id?petition_url=http%3A%2F%2Fwww.change.org%2Fpetitions%2Fask-starfleet-to-add-a-purple-uniform
=> { "petition_id": 949821 }

Note: A public API key is a required parameter on all requests, and a timestamp, endpoint, and request signature are required on certain requests. For readability, these parameters have been omitted from the tables and examples above.