Developers / API Documentation / Resources / Petitions

Signatures on Petitions

GET petitions/:petition_id/signatures

Returns signatures on a petition.

Request Parameters

Parameter Name Type Description
petition_id int (In URL) The petition from which the targets should be retrieved.
page_size int (Optional) The maximum number of signatures to return per request, but no more than 100. If omitted, returns a maximum of 10 signatures.
page int (Optional) The page offset by page_size signatures. If omitted, returns the first page by default.
sort string (Optional) The order by which signatures will be returned. Accepted values are time_asc and time_desc. If omitted, defaults to time_asc.

Response Data

An array of signatures. A maximum of page_size signatures will be returned, offset by the page number given.

Field Name Type Description
signature_count int The number of total signatures on this petition.
prev_page_endpoint string The API endpoint that can be called to retrieve the previous page of signatures. null if there is no previous page.
next_page_endpoint string The API endpoint that can be called to retrieve the next page of signatures. null if there is no next page.
page int The current page number.
total_pages int The total number of pages of signatures (of size specified by page_size)
signatures array The array of signatures.

The signatures array contains objects with the following data:

Field Name Type Description
name string Full display name of the signer.
city string Residential city of the signer.
state_province string (If available) The standard abbreviation of the state or province of the signer.
country_name string Full English name of the country of the signer.
country_code string The two-letter code of the country of the signer.
signed_on string of ISO-8601 datetime Date and time of the signature.

Example:

GET https://api.change.org/v1/petitions/48503/signatures?&page_size=2&sort=time_desc
=> { 
"signature_count": 6,
"prev_page_endpoint": null,
"next_page_endpoint": "https://https://api.change.org/v1/petitions/48503/signatures?page=2&page_size=2&sort=time_desc",
"page": 1,
"total_pages": 3,
"signatures": [{
"name": "Jean-Luc Picard",
"city": "La Barre",
"state_province": "",
"country_code": "FR",
"country_name": "France",
"signed_on": "2012-02-15T23:39:31Z"
},
{
"name": "William Riker",
"city": "San Francisco",
"state_province": "CA",
"country_code": "US",
"country_name": "United States",
"signed_on": "2012-02-14T10:02:23Z"
}]
}

GET petitions/:petition_id/signatures/recent

Returns an array of the 10 most recent signatures on a petition.

This is similar to

petitions/:petition_id/signatures?page_size=10&sort=time_desc

but will not return pagination information or endpoints.

Request Parameters

Parameter Name Type Description
petition_id int (In URL) The petition from which signatures should be retrieved.

POST petitions/:petition_id/signatures

Adds a signature to a petition. A request signature, is required for this request.

By adding signatures to a petition, the API user agrees to display the following text and links directly above or below the signature form:

This petition is powered by Change.org. By signing, you accept Change.org's terms of service and privacy policy.

Request Parameters

Parameter Name Type Description
petition_id int (In URL) The petition to which a new signature should be added.
auth_key string The petition authorization key.
source string The source code originally submitted to request the authorization key. (See Authorization Keys on Petitions.)
email string Email address of the signer.
first_name string First name of the signer.
last_name string Last name of the signer.
address string Residential address of the signer.
city string Residential city of the signer.
state_province string The standard abbreviation for the signer's state or province.
postal_code string Postal code of the signer.
country_code string Two-letter country code of the signer.
phone string (Optional) Mobile phone number of the signer.
reason string (Optional) The signer’s reason for signing.
hidden boolean (Optional) Whether or not the signer’s name will appear in the petition’s signature list and on their Change.org profile. If omitted, a signature is public by default. Accepted values are true and false.

Response Data

If the request is successful, the response will have an HTTP status code of 202 and a brief successful result message. If it is not successful for whatever reason, the status code will vary depending on the circumstance. See Response Codes.

Field Name Type Description
result string Whether or not the signature was successfully queued for adding to the petition. Either success or failure.
messages array (If applicable) An array of error messages.

Examples:

POST https://api.change.org/v1/petitions/48503/signatures
address=123%20Sesame%20St&auth_key=fb6dc0709b1e012f479b109add670a2c&city=New%20York&country=US&first_name=Hikaru&last_name=Sulu&phone=123-555-1234&postal_code=12345&state_province=NY
=> { "result": "success" }
POST https://api.change.org/v1/petitions/48503/signatures
=> {
"result": "failure",
"messages": ["No signature data received."]
}

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.