All requests are made on a specific API resource:[resource]

Content Type

The body of POST and PUT requests, including any relevant parameters, can be formatted as URL-encoded form data or Javascript Object Notation (JSON). The format is specified in the Content-Type HTTP header of a request.

The API assumes that the body of a request is URL-encoded form data unless a Content-Type header is specified. The following Content-Type headers are accepted:

Format MIME Type
URL-encoded form data application/x-www-form-urlencoded
JSON application/json

Request Validation

The parameters in each request must always be accompanied by an API key. Three additional parameters must be included on all requests that modify or update a resource: an endpoint, a timestamp, and a request signature. The request signature (detailed below) is generated by using the API user's secret token and a resource authorization key.


See Authentication for more information about API keys.


Requests that require a request signature require an endpoint parameter. The endpoint -- the path to which the HTTP request is made -- ensures that the request was sent to the intended enpoint since the request signature is generated with this value and checked against the actual request path. This mitigates against "man in the middle" attacks.




Requests that require a request signature require a timestamp parameter, which is the current date and time at UTC in ISO 8601 format. This mitigates against "replay" attacks. Requests submitted more than 5 minutes before or after the date and time indicated by the timestamp will be rejected.



Request Signature

The request signature parameter, appended to the clear-text parameters as rsig, ensures that the request originated from an authorized API user and, if applicable, that the user is authorized to perform the requested action.

The request signature is a 256-bit hexadecimal SHA-2 digest of the POST body or GET query string appended with the user's secret token and, for requests that require it, the resource authorization key.

Constructing Request Signatures

To construct a request signature, the components are ordered as follows:

[POST body or GET query string][secret token][authorization key, if applicable]

Then, a 256-bit SHA-2 digest is created of that resulting string. This is then passed as a parameter, rsig.

Example Request Signature

For example, when making a request to add a signature to a petition, whose petition_id is 4832, the clear-text parameters would be

Parameter Name Example
api_key 754a28309b20012f479b109add670a2c
timestamp 2012-04-18T21:02:00Z
endpoint /v1/petitions/4832
first_name Deanna
last_name Troi
address 3 Broadway
city New York
state_province NY
postal_code 12345
country_code US

The request signature is generated from the query string of this POST request along with the user's secret token and petition authorization key.

To construct the request signature, we take the POST body:


Then the secret token, in this case 003af2309b1f012f479b109add670a2c, and the authorization key, in this case b233f245f01666f479b179a1124701aa, are appended to the end of the string:


And the final request signature would be the 256-bit hexadecimal SHA-2 digest of the string above:


The signature is then appended as another parameter, rsig, to the clear-text body content. So the full request and return value would be

=> [202 success message]

Request Parameters

The following table summarizes the paramters required for requests:

Parameter Name Type Description Example
api_key string The user's API key. 754a28309b20012f479b109add670a2c
endpoint string (Requests with rsig) The path of the endpoint to which the API request is sent. /v1/petitions/48503
timestamp string of ISO-8601 datetime (Requests with rsig) The timestamp of the request: YYYY-MM-DDThh:mm:ssZ 2012-04-18T21:02:00Z
rsig string (For requests that create or modify a resource) A 256-bit SHA-2 hexadecimal digest of the POST body or GET query string, appended with the secret token and, if applicable, the resource authorization key. ac0889ce480e30151c08613093868d22e3 0d4fcb60cc42089313e9d6ccc5bcbc
varies varies All other clear-text parameters for the specific request.


A callback parameter can be specified on any request and the resulting response will be wrapped in the specified callback method.

Rate Limits

A maximum of 50,000 requests per day using the same API key are allowed. A maximum of 10,000 requests per day using the same petition authorization key are allowed.

Upon special request and coordination with, these limits may be lifted.