Campaigns are the core advocacy content of Rally Congress. A Campaign is essentially a landing page that can have different "actions" for site visitors. Those actions can include sending letters to lawmakers, making phone calls to lawmakers, or posting comments on social media.
A GET request on the campaigns resource will retrieve list of current Campaigns and related actions.
GET BaseURI/campaigns
Add a campaignId value to the request URI to get details on a single campaign:
GET BaseURI/campaigns/{campaignId}
The Campaign details include the landing page title and text, and various display settings.
You can also GET each of a Campaign's actions to retrieve specific elements for that action.
GET BaseURI/campaigns/{campaignId}/{actionType}
The API allows you to build a website or mobile application to provide a custom "Take Action" experience for your website visitors. You can retrieve the form fields that a person must fill out, as well as the sample letter and targets.
The actionType value can be one of the following:
| Parameter | Description |
|---|---|
| letter | Action to generate letters to lawmakers. |
| Action to generate tweets to lawmakers. | |
| phone | Action to provide a lookup and call reports for phone calls to lawmakers. |
| petition | General internet petition (no message delivery). |
| Action to generate facebook comments or other activity to lawmakers. |
GET BaseURI/campaigns/abcd1234/letter
A GET request on a Campaign action returns a representation of an html form. The form consists of the different fields needed for the user to complete the action.
All form fields have the following basic properties: Label (or Title), a Type, and whether or not the field is isRequired. The request also returns the sample letter(s) and legislative targets.
The GET request to a specific Campaign action can include optional parameters:
| Parameter(s) | Description | Returns |
|---|---|---|
| zipcode | A five- or nine-digit U.S. ZIP Code | City, State, and all Targets for the ZIP Code |
| Supporter's email address | Supporter ID, targets, and record of the Supporter's past action if it exists | |
| supporterId | Supporter's Rally Congress ID | Targets and record of the Supporter's past action if it exists |
| customId | Supporter's external or custom ID | Targets and record of the Supporter's past action if it exists |
| street, city, state, and zipcode | A valid U.S. street address (use two letter state postal code) | Targets for this Campaign action and address |
GET BaseURI/campaigns/{campaignId}/letter?zipcode=34209
NOTE: A ZIP Code query will return multiple lawmakers if the ZIP Code covers more than one district.
GET BaseURI/campaigns/{campaignId}/letter?email=supporter@example.com
The Campaign API also accepts a message for delivery to elected officials, as well as supporter information for storage in your Rally Congress database.
The process of sending a message to Rally Congress for delivery to lawmakers is consolidated into a single POST.
A POST to Campaign letter action will UPDATE or INSERT a Supporter, add a new Message for that Supporter, log the action taken for that Campaign, and place the new Message into the delivery queue for each and all of the target Lawmakers.
POSTs to send a message for delivery must be associated with a Campaign letter action. Many lawmakers request additional information such as the URL of the Campaign and the topic of the Campaign. This information is created when the Campaign is first set up in the control panel.
POST BaseURI/campaigns/{campaignId}/{actionType}
POST BaseURI/campaigns/123456/letter
NOTE: The API is for potentially complex, finely grained integrations. Alternatively, you can embed a campaign directly in your web page.
To test the API without actually sending messages to lawmakers, include the parameter "mode" and the value "no_delivery" to your request as either a POST or GET parameter.
To create or update a Supporter, the POST request MUST include ONE of the following parameters:
| Parameter | Description | Returns |
|---|---|---|
| supporterId | The id for this Supporter in Rally Congress | Existing Supporter, Action ID |
| customId | The custom or external ID for this Supporter | Existing Supporter, or if submitted with an existing Supporter ID or existing or new email, the value is appended to that Supporter record for future use |
| A valid email address (Used as a unique ID if no Supporter ID or Custom ID is present or exists) | Existing Supporter, or creates a new Supporter and returns that |
POST email => returns Supporter ID (if it exists) and whether or not the Supporter has taken action. (Technically this should be a GET on Supporter and then a GET on the campaign action, sort of a shortcut)
POST address PLUS email => returns targets for this action, Supporter ID + Custom ID, action taken or not
POST letter PLUS name/address, or Supporter ID, Supporter Custom ID, or Supporter Email address
| Parameter | Description |
|---|---|
| subject | The plain text subject of the message for lawmakers. If no subject is submitted, Rally Congress will use the Campaign title if a lawmaker requires a subject. |
| message | The plain text of the message for lawmakers. Most offices do not support html or rich text messages. Maximum length of 10,000 characters suggested; longer messages may be truncated for some offices. |
The API is flexible enough to support many different patterns in your applications. If you have another pattern in mind, just let us know and we'll try to accommodate you. The following examples take two submissions, but you can also collect the Supporter name, address, email, and letter in one form on your site, and POST them to the API in a single call.
The website may show the form in one step or multiple steps, or implement an AJAX-style interaction, but there is a basic assumption that the API will receive address information for a user so that alert targets can be resolved to the lawmaker recipients.
There are other scenarios where you already have name and/or address information for a user. In that scenario you can POST the email to return the Supporter's customId or Rally Congress supporterId in Rally Congress to see if they've taken action already.
If you have the customId, Rally Congress SupporterId, or Supporter's email address, you can check Rally Congress to see if the Supporter exists to avoid the need to collect their address information. In this scenario, just pass the ID or email with the information to the API.
The response for a message POST can be:
{
"requiredFields": [
],
"queuedMessages": [
{
"deliveryId": "48545",
"recipient": { ... }
},
{
"deliveryId": "48546",
"recipient": { ... }
},
{
"deliveryId": "48547",
"recipient": { ... }
}
]
}