How To Build an App to Call/Write Congress

Joshua Tauberer
Civic Tech Thoughts from JoshData
12 min readDec 24, 2016


Americans have a tradition of communicating with their representatives in Congress to express their views and hold them accountable. Technologists have a tradition of building apps around this concept.

First let’s be real about why this matters — or doesn’t

Let’s be real — “writing your rep” (or calling your rep) isn’t effective advocacy, not most of the time at least. That’s because the United States is filled with people communicating with their representative and senators already.

Each congressional office receives hundreds-to-thousands of messages each day. They don’t “read” them. They sort the messages into buckets, send out bulk replies, and if you’re lucky the low-level staff who process constituent mail and phone calls might tell the representative or senator a total count of messages received on each subject. They do things this way not because they don’t want to hear from their constituents (they do) but because they hear from so many constituents already — more than they can keep up with.

If you’re goal is to make it easier for people with access to computers and smart phones to communicate with Congress, chillax — those folks are already doing it and they are probably wasting their time anyway.

And if you think communicating more is going to make Congress more accountable, you have it backwards. The question is not how to do it more, but how to make communicating with Congress more effective.

Before going any further, you should study the following:

a) My primer on the reality of civic technology:

b) The Congressional Management Foundation’s decade-long research project into citizen communication with Congress:

c) The recent tweets by Emily Ellsworth — especially the parts about thinking about it from the staffer’s point of view.

d) Daniel Schuman’s post on congressional staff cuts. If you want there to be staff to read the messages, then you want Congress to stop cutting off its own legs:

There are still a few good reasons to care about this.

The flip side is that we can’t give up on the idea of petitioning our government. It is an important tradition, and it is a useful tool as a part of civics training and organized advocacy efforts that go beyond letters and calls.

Lots of people have build constituent communications tools (letters or phone calls). I’ve done it. Three times! On GovTrack you can call your rep and senators about any bill via my spin-off project

Then there’s POPVOX (disclaimer: I have financial ties), (they use GovTrack’s data), callmycongress (also uses GovTrack’s data), (also uses GovTrack data, sorta), care2 and causes (petitions that turn into letters I think?), and on and on.

The apps that help you call your rep often give you a script and either tell you your rep’s phone number or else uses a nifty telephony tool to dial the constituent and then patch them into their rep’s office automatically.

Chances are what you want to build already exists.

But if you really want to build a similar tool, here’s how not to reinvent the wheel.

(Don’t confuse any of this with “case work.” Case work is when a constituent asks their rep or senator for help with an issue they are having with a federal agency, such as not receiving a Social Security check. That’s an important service that is unrelated to what I’m discussing here.)

First, you need a database of current representatives and senators in Congress.

Fortunately there’s an open source project that I started for that:

The congress-legislators database contains biographical and legislative information for each currently serving representative and senator, including DC office mailing addresses and phone numbers. If you use this data, please remember that you are relying on the time of volunteers who are keeping it up to date for you — please consider helping out too.

Also keep in mind that the data changes regularly. If your data isn’t updated each day, you may be sending constituent communications to the wrong place. That’s bad. And it gets a little crazy when one Congress ends and the one next begins. If you think that’s around election or presidential inauguration time (it’s not), you’ve got a lot of research ahead of you.

Then you need to determine which representative and senator represents your user.

For senators that’s easy — just ask the user which of the 50 states they live in.

If the user doesn’t live in a state (residents of the 6 U.S. territories, expatriates living abroad, and members of the military), they’re out of luck for contacting a senator unless they have an address in a state.

To contact a representative (i.e. a member of the House of Representatives, aka a congressperson), you have to determine which congressional district the user lives in.

Don’t limit users to the 50 states!

There are 441 representatives: 435 real representatives from the 50 states and then 6 non-voting delegates from the U.S.’s territories. Two of those territories have a larger population than some states, so don’t discount them just because Congress doesn’t consider those folks worthy of proper representation. (Use the congress-legislators database above to get a complete list of the states and territories that have representatives in Congress.)

Expatriates living abroad and members of the military should use an address within the United States if they have one. If they don’t, they’re out of luck.

Don’t offer the user the ability to contact a representative or senator that doesn’t represent them.

In most cases, if you write or call a senator of another state or a representative of another district, they simply won’t care. They won’t open your letter and they won’t tally your call. If you offer this to your users, you are wasting their time.

When they catch on that their messages are getting null-routed, they are not going to be happy. And if what you really care about is a cause and not a tool, then you want to be using their time effectively obviously.

Asking for their 5-digit ZIP code is not correct.

If you get a ZIP-to-district database, it will be wrong 10–20% of the time. That’s because ZIP codes don’t line up with congressional district boundaries at all and both ZIP codes and congressional district boundaries change faster than these databases are updated. (ZIP-plus-four’s, the 9-digit ZIP codes, are fairly reliable. You could use a database of those. But your users will rarely know their ZIP+4.)

You need to ask for their actual home address.

The only reliable way to determine a person’s congressional district is to ask them for their home address (where they vote), then using a “geocoding” service to turn the address into a latitude-longitude coordinate, and then use a “geospatial” (GIS) database of congressional district geographic boundaries. (In a mobile app you could use geolocation if the user is at home! and skip the first step.)

GovTrack’s Congressional District Look-up

Yikes. It’s hard to do this right!

Just pay a company like (free tier then $1 per 1,000 lookups) or CDYNE (~$10 per 1,000) or the Google Civic Information API (free). They each have an API to turn an address into a congressional district and it’s fairly inexpensive. (I recommend

Keep in mind:

  • You can’t trust an API to provide correct answers just because they say they do geocoding. How geographically accurate is it? Do they have recent street data? Do they have the latest congressional district boundaries?
  • Around election time be extra careful because elections are based on the next set of district boundaries, but contacting your representative is based on the district boundaries in the last election until the new representatives take office (that happens on Jan 3rd's). Check with your geocoding provider what boundaries they are using and make sure you get updates at the right time.

If you want to roll your own GIS tool…

If you want to roll your own address-to-district GIS tool, or at the least understand what you’re getting into with any of this, you can see how we do it on GovTrack here, thanks to some awesome work by volunteer Aaron Dennis:

And source code:

We use Mapbox for not only displaying a map visually but also geocoding street addresses and the GIS query of district boundaries to determine the congressional district (they provide us a huge discount — thanks Mapbox! — but the list price is around $2 per 1,000 lookups).

Congressional district boundaries change periodically: always for the election after decennial Census years (2012, 2022, etc. election years) and then occasionally due to court-ordered redistricting when states try to disenfranchise people. Plus around election time people get really confused about when those district boundary updates take effect. If you want to get this stuff right, you have to follow this stuff carefully and ask an expert (like me).

Ok so now you have a congressional district number, like AK-0 (Alaksa’s at-large congressional district) or NY-13 (New York’s 13th congressional district). You can use the congress-legislators database mentioned earlier to look up who the representative is and either their mailing address or phone number.

Postal mail is ok, but it’s slow.

Sending a letter by postal mail to a representative or senator’s office address (usually their DC address) is good. That’s a totally acceptable way of contacting Congress.

All postal mail that goes to the U.S. Capitol offices is irradiated at an off-site location to protect folks from anthrax or something. That causes a delay of a few weeks for all postal mail. That’s fine, as long as you don’t mind the mail coming in late.

And of course you have to pay postage.

Don’t fax instead. That’s just weird. No representative or senator actually has a fax machine anymore. Their fax numbers are virtual fax machines that just email them a scan of what was faxed. It’s weird. Don’t do that. Let them move on from 1990s technology.

What about email?

Representatives and senators don’t have email addresses, at least not ones they give to constituents.

What about webforms?

They all instead have a contact form on their website. Using the website contact form is a good method to contact them. It’s no less effective than a postal letter. It might be more effective because it goes straight into the system the representative or senator uses to sort and count their mail. You want to be counted, so that’s what you want.

But if you want to build an app that actually submits the letter so the constituent doesn’t have to fill out the form themself, automating this is hard. Don’t try. Maintaining an automated system that reliably fills out these webforms is extremely time-consuming. Do the math. If there are 541 representatives and senators and each revamps their webform once a year, that’s more than one changed form each day that you have to deal with.

There is a community project to try to solve that:

and it’s the basis of, but I don’t know how to use this data or if it’s reliable.

(There are other intractable problems besides that that I won’t get into here.)

You can, instead, and for representatives only, apply to send constituent letters in electronically through the House of Representative’s new API:

Better yet, just pay a company like VoterVoice (they use GovTrack data) or POPVOX (see earlier disclaimer) to do this for you. It’s going to be a lot cheaper if you just pay someone to submit the messages than if you build a new system yourself.

If you are writing a letter, offer a template.

If you are helping a user write a letter, offer a template and useful advice. Give them the best shot at being effective and not wasting their time:

a) Be very clear about what you want the Member of Congress to do, i.e. how to vote on a bill (give the bill number and title), whether to cosponsor a bill, etc. Make sure you’re asking for something the Member of Congress can actually do.

b) Have the user write a short, personal message — a short personal story is best. Showing that the user is actually affected by the issue you’re having them write about is important and distinguishes the letters from others without personal stories.

c) Be respectful. Don’t demand. Don’t make threats about not voting for them (it’s an empty threat!). And certainly don’t talk about making or not making a campaign contribution — that could be illegal (it’s potentially bribery!). Remember that it’s essentially underpaid interns who read the mail, and your job is to get the intern to want to help you — not to want to ignore you.

Phone calls work too, but be even more respectful.

Finally there’s the phone call.

A phone call is fine. But. Please be even more responsible about this because you are going to be having your users talk to an actual human being on the other side who deserves respect as much as anyone. You’re also using up the office’s valuable time, so please consider that you are not the only person whose needs are important — the office has other constituents to help too.

So, like, obviously a phone call campaign is going to be more effective than a letter writing campaign. Shouting louder tends to be more effective. Don’t think that this is about technology or finding a secret advocacy method. You’re just shouting louder when you use the phone, escalating the advocacy arms race of being loud.

[This no longer true as of early 2017.] At GovTrack, I use Twilio. I give the user a script to read on the phone call. They enter their phone number, and GovTrack calls them up and — via Twilio — connects their call to their representative’s office. The congress-legislators database linked above has the phone numbers you need.

You can see my source code for it:

Using Twilio like this has two advantages:

a) It’s a little easier to call the user than to have the user call their representative.

b) I record the calls (with the permission of the user) and listen to them to understand whether these phone calls are meaningful. It’s valuable data for me, like other app analytics.

Like a postal letter, a phone call has a transactional cost but at Twilio’s pricing it’s about 10x cheaper than postage.

You must report your numbers & respect the institution.

It’s all too easy to say you had a million users write or call Congress, but if you don’t deliver messages in a prompt and effective manner then you’ve sold snake oil — jeopardizing the very institution of petitioning government. This is real stuff. We have enormous ethical responsibilities when we create tools like this.

I know the challenges that need to be overcome to be effective, and I will call you out on them if I don’t see that you’ve addressed them.

  1. If you deliver written messages to Congress, then you must report how many messages were successfully received. If you don’t, I will assume you aren’t delivering all of your user’s messages, and I will call you out on it.
  2. If you are having users make phone calls, then you must report how much staff time you are causing to be taken up and you must report how you’ve verified that your users are not harassing congressional staff. If you aren’t bothering to check, I will call you out on it.

Since adding this tool to GovTrack in 2013, users have made 5,288 calls to Congress with an average call duration (for connected calls) of 85 seconds. There has been a caller from nearly every congressional district. It’s pretty cool. As I mentioned above, I record the calls and have spot checked that they are respectful.

And that’s what I know about writing and calling your rep. I’ll update this post as I think of other things.

I’ve been working on creating open infrastructure around congressional data for more than a decade. It’s hard work. I only barely make any money when I spend time on this. If you use my stuff, please think about how you can contribute back to the open legislative data ecosystem and/or convince your funders to fund me… I mean… it.