contact-congress is a data format for legislator contact forms, and its House half was frozen in 2017

This is a format and a dataset, not a contact tool

The project defines an open data format to describe the contact forms of members of Congress, and it is working on a definitive, updated list of active legislators' contact forms written in that format. Once the files exist, they can be used to power any system that lets US citizens send messages to their elected representatives.

That scope statement is important, because the project is very clear about what it is not. The FAQ asks whether you can drop your contract with a third party vendor and answers that this is just data. Even with data for everyone, you still need to build a system that integrates it, and there is nothing here for tracking and storing errors and mistakes, for strategies of retrying, or for storing user data or success statistics.

What you avoid is keeping up with constantly shifting websites. That is the specific labour this dataset absorbs.

The motivation is stated in the same terms. At present, the only ways to send electronic messages to members of Congress are to visit each legislator's contact form or to use a proprietary third party vendor on an advocacy organisation's website. The contact forms are described as cumbersome and difficult to use, and the vendors as expensive. A common, up-to-date dataset allows for simpler and better tools for dialogue with representatives.

The audience is therefore open government and advocacy organisations that want to build their own sending tool, not individual constituents.

A file per legislator, keyed by Bioguide ID

The unit of the dataset is a YAML file per member of Congress, named after that member's Bioguide ID and stored in the members directory. The project ships a documentation/schema.md that describes the schema used to represent the steps involved in filling out a member's web form, which is the part of the repository that defines the format itself rather than the data.

The project description frames the whole effort as reverse engineering, describing the goal as sending electronic written messages to members of Congress by reverse engineering their contact forms. That framing explains the shape of the data. A contact form is not an API, it is a sequence of HTTP requests with specific field names, specific select options and a specific submission endpoint, and describing it in a structured way means recording those steps in a form a program can execute.

Because the files are keyed by Bioguide ID, the dataset joins cleanly with other data. The FAQ points to the unitedstates/congress-legislators project for detailed, reliable data about every current and historical member of Congress, stored as YAML, and says it is easily connectable to this project via each member's Bioguide ID.

That join is the practical reason to prefer this format over scraping on demand. The legislator metadata, the bioguide identifier and the contact form description become three separate, independently maintained datasets that combine on a stable key.

Contributing a file takes a ticket, a bookmarklet and a test run

The contribution procedure is prescribed in detail, and the order matters because the ticket reserves the member before the work starts.

The documentation asks contributors to visit the contribution guide for the full description, and then summarises it as a sequence:

1. [Reply to an open ticket](https://github.com/unitedstates/congress-contact/issues?labels=MoC&page=1&state=open) stating that you are currently working on a congress member's form.

2. [Use the bookmarklet](http://unitedstates.github.io/contact-congress/) to generate a new YAML file.

3. Save the generated file in `/members` as `[bioguide].yaml`, where `[bioguide]` is that member's *Bioguide ID*.

4. [Submit a pull request](https://github.com/unitedstates/congress-contact/compare/) with the new file.

5. Test the YAML file using [congress-forms-test](http://efforg.github.io/congress-forms-test/) and make changes to the file as necessary.

The bookmarklet is the interesting piece of tooling. Rather than hand writing a description of a form, you open the legislator's contact page, run the bookmarklet, and it captures the form structure into a YAML file. The status list confirms that the bookmarklet and the testing suite were both completed as separate work items.

Step five is where most of the effort goes, and it is not optional: the file has to be validated against the live form with congress-forms-test, and the documentation expects changes as a result of that test. A YAML file that describes a form which has since changed is worse than no file, because a sending system will submit to a form that no longer exists and report success.

The project underlines the stakes in its own words: each file contributed to the dataset will potentially allow hundreds of US citizens to contact their representatives.

The House files were frozen when the CWC API arrived

The status list is candid about coverage, and one line in it matters more than the rest.

Completed items are a standardised YAML format for describing legislator contact forms, a bookmarklet to generate YAML files, a testing suite to error check generated files, and YAML files for almost all 100 members of the Senate and almost all 439 members of the House of Representatives. The one open item is that the files are tested.

Then there is the note. As of January 1, 2017, YAML files for members of the House of Representatives are no longer actively being maintained, because the House uses the CWC API to send messages instead of contact forms. The project links to the House documentation for the CWC API and explains that its application for reading these YAMLs and submitting messages, Phantom of the Capitol, has been updated to use the CWC API, in a branch of the EFForg/phantom-of-the-capitol repository.

So the dataset is asymmetric. Senate files are the live use case; House files are a historical artefact that still exists and is still useful for anything that needs to describe an older House contact form, but will drift further from reality every election cycle.

The project is still open to pull requests for House YAMLs, and says it will keep merging them if those are files you still use. That is the right posture for a dataset whose value is a shared, updatable description of forms that are changing underneath it.

What the dataset deliberately leaves to the integrator

The FAQ section is where this project is most candid, and it is worth reading twice before you build on it.

The first question is whether you can drop a vendor contract, and the answer is that you cannot, because this is just data. The enumerated gaps are specific: there is nothing for tracking and storing errors and mistakes, nothing for strategies of re-trying, and nothing for storing any sort of user data or success statistics.

Those three gaps are exactly the parts of a message sending system that are hard and expensive. Rate limiting, retry with backoff, delivery confirmation, suppression lists, campaign analytics and audit trails all live outside this repository, and whoever builds the tool owns them. The dataset saves you from maintaining parsers for shifting websites, not from operating a sending service.

The second question is about other legislator data, and the answer points to the congress-legislators project, described as detailed and reliable data about every current and historical member of Congress, stored as YAML and easily connectable via the Bioguide ID.

The organisations involved give a sense of the intended users. The Sunlight Foundation led development and was to integrate the data into OpenCongress.org, and the Electronic Frontier Foundation was to use it with their congress-forms implementation to advocate for better technology laws and regulations. Both are advocacy tooling rather than consumer messaging, and that is the use case the format was designed for.

Public domain, no releases, and a recently touched repository

The project is dedicated to the public domain, and the licence file says so explicitly. The contribution terms state that the project is in the public domain within the United States and that copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication. All contributions are released under the same dedication, and submitting a pull request means agreeing to comply with the waiver.

For an organisation that wants to embed the data in a commercial advocacy tool, that removes the licensing question entirely. There is no attribution requirement and no share alike condition, unlike the Creative Commons licences that are common for open government data.

The repository structure shows a working project with the usual supporting files. There is a members/ directory holding the per legislator YAML, a documentation/ directory holding the schema, a support/ directory, a CONTRIBUTING.md, a current_issues.md file, and a .travis.yml file at the root. The presence of current_issues.md alongside the members directory is a good sign for anyone about to rely on the data, because it is where outstanding problems are tracked.

There are no GitHub releases, so there is no version to pin and nothing to upgrade. The repository is not archived and the last push was on 2026-09-18, so files are still being edited in place.

The practical takeaway for an adopter is that this data behaves like a wiki rather than like a dependency. Read current_issues.md before you rely on a file, validate it with congress-forms-test, and treat any file you cache as a snapshot with an expiry date rather than as a stable API.

Editorial conclusion

Use contact-congress if you are building a tool that sends constituents messages to legislators and you want the form structure described once, in a reviewable format, instead of scraping each office site yourself. Do not pick it as a system to run, because the project states plainly that it is just data with no tracking, no retry strategy and no user data storage, and check the freshness of any House file you rely on, since those stopped being maintained on 2017-01-01 in favour of the CWC API. Before you use a file, validate it with congress-forms-test and confirm that the target office still uses that form, then join legislator metadata through the Bioguide ID using the congress-legislators project.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. Project website
4. README
5. unitedstates/contact-congress on GitHub