API Documentation (version 3.02 December 21, 2015)

Welcome to the Rally Congress API.

Does your organization have technical resources and want to go beyond the existing action pages? Designed using REST principles, the API provides your account with resource-oriented URLs that you can securely access and use to build your own applications or user interfaces. The API allows you to retrieve campaign and supporter data from your account, and send supporter address data and messages to Rally Congress for delivery.

Since the API is based on REST principles, it's relatively easy to write and test applications. The Rally Congress API uses built-in HTTP features, like HTTP authentication and HTTP verbs (GET, POST), which are understood by off-the-shelf HTTP clients. You can use your browser to access URLs to view responses, and you can use pretty much any HTTP client in any programming language to interact with the API. HTTP response codes and JSON are returned in all responses from the API, including errors.

Base URL

All URLs referenced in the documentation have the following base:

https://api.rallycongress.com/v3/

NOTE: The Rally Congress API is secured over HTTPS-- to ensure data privacy, unencrypted HTTP traffic is not supported.

Resources

Every Rally Congress Account has the following resources:

  • Campaigns Get campaigns, action forms, sample letters, and POST to submit messages for delivery
  • Supporters Fetch, create and update supporter records

Making a Request

Authorization

All API calls are secured by HTTP Basic Auth. All requests must include your Account ID (username) and Auth Token (password). You can create and retrieve ID and Auth Tokens in the administrative control panel. Log in and go to the upper right corner, select the "Account Settings" dropdown menu and choose "API".

Most HTTP clients (including web-browsers) present a dialog or prompt for you to provide a username and password for HTTP basic auth. Most clients also allow you to provide credentials in the URL itself. For example, this pattern will work:

https://{AccountID}:{AuthToken}@api.rallycongress.com/v3/campaigns

Possible GET Response Codes

In addition to the HTTP status code, the response will contain body text formatted in JSON.

200 OK Rally Congress API call was successfully processed and the response contains the data requested.
302 FOUND A redirect; you can GET the representation at the URI in the Location response header.
304 NOT MODIFIED Your client's cached version of the representation is still up to date.
400 BAD REQUEST The request had incorrect parameters.
401 UNAUTHORIZED The authentication failed.
404 NOT FOUND The requested resource was not found-- basically a bad URL. If a valid request returns no results, that will still return a 200 OK.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 INTERNAL SERVER ERROR Our system is experiencing an unexpected internal error.
503 SERVICE UNAVAILABLE We are temporarily unable to return the representation. Please wait for a bit and try again.

Creating Resources with the HTTP POST Method

Creating a resource involves performing an HTTP POST to a resource URI. In the POST, you represent the properties of the object you wish to update as form urlencoded key/value pairs. Most browsers encode POSTs this way by default. But be sure to set the HTTP Content-Type header to "application/x-www-form-urlencoded" for your requests if you are writing your own client.

Possible POST Response Status Codes

200 OK The request was successful, we updated the resource and the response body contains the representation.
201 CREATED The request was successful, we created a new resource and the response body contains the representation.
202 ACCEPTED The request was successful, but additional information is needed to finish the action. The response body contains the unique ID needed to submit with the additional information to complete the action.
400 BAD REQUEST The data given in the POST or PUT failed validation. Inspect the response body for details.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to create the resource.
404 NOT FOUND The resource wasn't found.
405 METHOD NOT ALLOWED You can't POST to the resource.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 INTERNAL SERVER ERROR There was a server error and we couldn't create the resource. Please try again.

Paging Information

If the response has many results, the API returns partial results in a single "page". The representation includes the following information:

PROPERTY DESCRIPTION
uri The URI of the current page.
firstpageuri The URI for the first page of this list.
nextpageuri The URI for the next page of this list.
previouspageuri The URI for the previous page of this list.
page The current page number. Zero-indexed, so the first page is 0.
pagesize The number of items returned in each page.
totalResults Total number of results found for the request. This number can change in real-time if the Campaign is active.