On contacting members of the US Congress using Phantom of the Capitol API and Huginn

Below is a method used to periodically contact members of the US Congress using the Phantom of the Capitol API and the Huginn platform.

Background

If you've ever tried to email a member of Congress, you've probably realized how unusual the process is. Unlike most of us, members of Congress don't make email addresses available to the public. Instead they rely on cumbersome web forms. Therefore each time a constituent would like to contact their representative they must visit the website of each particular congress person and fill out a non-standard web form, which is needless to say time-consuming.

After looking around for a better solution I quickly discovered democracy.io from the Electronic Frontier Foundation (EFF), which allows you to use a single web form to contact several members of Congress at once and they offer an API, but there isn't really information about it online. I've emailed them about using their API, but as of this writing I'm still waiting.

In the mean time, I discovered that democracy.io actually uses another EFF API called Phantom of the Capitol, which allows users to retrieve the form fields from all of those congressional web forms and submit messages all in one place. After successfully testing the API in Terminal, I started thinking about how I could integrate it into an instance of Huginn that I was already running in order to automatically send an email every week.

Part 1: Phantom of the Capitol API

The first thing you need in order to use the Phantom of the Capitol API (PotC API) is the so-called bio ID of the congress person you would like to contact from the Congressional Biographical Directory.

Once you search for the congress person, the bio ID can be found in the URL. For instance:

Once you have the ID, you need to see which form elements the congress person's website requires by running the POST /retrieve-form-elements command. To do so simply take the code from PotC, insert the bio ID and run in Terminal on Mac, Linux or probably even Windows 10’s new bash shell.

curl -H "Content-Type: application/json" -d '{"bio_ids": ["Y000066"]}' https://congressforms.eff.org/retrieve-form-elements

If successful, you will get a JSON response with a list of the required fields for their web form. I would recommend copying that into a code editor or notepad to sort it out.

Now it's time to fill it out. It may seem like a hassle at this point, but remember you only have to do this once.

Over at PotC, find the POST /fill-out-form section. They have an example that you can start with; replacing the bio ID and fields with those from your JSON response from the previous step. Don't forget to replace http://localhost:9292/fill-out-form with https://congressforms.eff.org/fill-out-form unless you are self-hosting PotC.

$ curl -H "Content-Type: application/json" -d '{"bio_id": "A111111", "campaign_tag": "stop_sopa", "fields": {"$NAME_FIRST": "John", "$NAME_LAST": "Doe", "$ADDRESS_STREET": "123 Main Street", "$ADDRESS_CITY": "New York", "$ADDRESS_ZIP5": "10112", "$EMAIL": "joe@example.com", "$MESSAGE": "I have concerns about the proposal....", "$NAME_PREFIX": "Grand Moff"}}' http://localhost:9292/fill-out-form

If everything goes smoothly you'll receive {"status":"success"}. Now to setup Huginn so that your message is sent, let's say, weekly.

Part 2: Huginn

If you're not familiar with Huginn, it's a great project that allows you to program all sorts of tasks to occur automatically. It has been described as a mix between IFTTT and Yahoo Pipes, except you run it on your own server.^[1]

Setting it up to run on your own server or VPS like Scaleway or DigitalOcean^[1:1] can be a bit tricky but it is absolutely worth it in my opinion. There are some really neat and interesting things that you can automate with Huginn. For instance, I currently have mine monitoring apartment listings and job openings in my area. When it finds something it emails me or sends a notification via Boxcar.

Inside of Huginn, I've used the Post Agent to submit the message weekly via the PotC API.

In the option section you must fill in three items. If you click on Toggle View, it's a lot easier.

post_url: https://congressforms.eff.org/fill-out-form`
content_type: json
payload: {"bio_id": "A111111", "campaign_tag": "stop_sopa", "fields": {"$NAME_FIRST": "John", "$NAME_LAST": "Doe", "$ADDRESS_STREET": "123 Main Street", "$ADDRESS_CITY": "New York", "$ADDRESS_ZIP5": "10112", "$EMAIL": "joe@example.com", "$MESSAGE": "I have concerns about the proposal....", "$NAME_PREFIX": "Grand Moff"}}

You shouldn't need to change any other options.

Here's a JSON snippet you could use for a template.

{
  "post_url": "https://congressforms.eff.org/fill-out-form",
  "expected_receive_period_in_days": "1",
  "content_type": "json",
  "method": "post",
  "payload": {
    "bio_id": "SXXXXXX",
    "fields": {
      "$NAME_PREFIX": "Blah Blah Blah",
      "$NAME_FIRST": "Blah Blah Blah",
      "$NAME_LAST": "Blah Blah Blah",
      "$ADDRESS_STREET": "Blah Blah Blah",
      "$ADDRESS_CITY": "Blah Blah Blah",
      "$ADDRESS_ZIP5": "Blah Blah Blah",
      "$PHONE": "Blah Blah Blah",
      "$EMAIL": "Blah Blah Blah",
      "$MESSAGE": [
        {
          "tag": "p",
          "html": "Dear Blah Blah Blah,"
        },
        {
          "tag": "p",
          "html": "Blah Blah Blah"
        },
        {
          "tag": "p",
          "html": "Respectfully yours,"
        },
        {
          "tag": "p",
          "html": "Blah Blah Blah"
        },
        {
          "tag": "p",
          "html": "Blah Blah Blah"
        },
        {
          "tag": "p",
          "html": "Blah Blah Blah"
        }
      ],
      "$TOPIC": "Blah Blah Blah"
    }
  },
  "headers": {
  },
  "emit_events": "true",
  "no_merge": "false"
}

Press Save and that's it! Easy peasy. I'm still looking for something similar to PotC to contact state legislators, so if anyone has any ideas, let me know.

---

There is an automated deployment available for DigitalOcean, but again I've never tried it. ↩︎ ↩︎