Campaigns

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.

GET Campaign

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 Campaign Action Elements

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.
twitter 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).
facebook Action to generate facebook comments or other activity to lawmakers.
GET BaseURI/campaigns/abcd1234/letter

Form Fields

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.

Parameters

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
email 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

POST to a Campaign's Action to Add Supporters and Send Messages

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
email 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.

Sample Patterns

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.

Two Steps: Get Zip Code, Then Supporter's Letter, Name, Street Address & Email

  1. Potential supporter visits organization's website
  2. Website asks supporter for Zip Code
  3. Website server GETs Campaign API URI with Zip Code
  4. API returns that Campaign action's possible targets based on Zip Code
  5. API also returns form representation and sample letter for that action
  6. Website shows the supporter the form and sample letter. That person edits letter and provides name, street, telephone (if required), and email address
  7. Website POSTs letter, name/address/telephone information, and email address to API
  8. API validates data and then creates or updates that supporter information in Rally Congress database
  9. API places letter in delivery queue for the targets
  10. API logs the action taken for reports and the supporter's record
  11. API sends the supporter a confirmation email
  12. API returns Delivery IDs and final target lawmakers in response
  13. Website shows thanks or other message to supporter

Two Steps: Get Address, Then Supporter's Name, Letter & Email

  1. Potential supporter visits organization's website
  2. Website asks for address info
  3. Website server GETs address to Campaign API URI
  4. API validates address. If valid it returns that Campaign Action's targets based on address, if invalid it returns an error message
  5. API also returns sample letter for that Action
  6. Web site shows letter in a form to the potential supporter, who edits the letter and provides name and email address
  7. Website submits letter, address information, and email address to API
  8. API validates email, then creates or updates supporter information in user database
  9. API places letter in delivery queue
  10. API logs the action taken for reports and the supporter's record
  11. API sends the supporter a confirmation email
  12. API returns Delivery IDs in response.
  13. Website shows thanks or other message to user

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.

Check for an Existing Supporter and Existing Action

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.

  1. A member of the organization visits the organization's website, organization knows their email address
  2. Website server GETs Campaign API with email as query parameter
  3. API returns that supporter's ID and history, if any, for the Campaign action
  4. API also returns that Campaign action's possible targets based on the supporter's address
  5. Website POSTs that supporter's email or supporterId, and message for delivery, to the Campaign action URI
  6. API places letter in delivery queue
  7. API logs the action taken for reports and the supporter's record
  8. API sends the supporter a confirmation email
  9. API returns Delivery IDs in response.
  10. Website shows thanks or other message to the Supporter

Response Format

The response for a message POST can be:

  1. Success (201 CREATED), and list of recipients and delivery IDs
  2. Partial Success (202 ACCEPTED), returns letter ID and additional fields that need to be filled out
  3. Failure (400 BAD REQUEST), and list of validation errors
{
    "requiredFields": [

    ],
    "queuedMessages": [
        {
            "deliveryId": "48545",
            "recipient": { ... }
        },
        {
            "deliveryId": "48546",
            "recipient": { ... }
        },
        {
            "deliveryId": "48547",
            "recipient": { ... }
        }
    ]
}