Representatives

The representatives endpoint can determine who represents a user living at a certain address in the United States. We strive to make the API flexible for many different location input types, depending on how much information your users are willing to share.

Currently we support these offices within the US:

House Members
Senate Members
Governors (available upon request)
Secretaries of State (available upon request)
State Legislatures (available upon request)

Representative response

The reps endpoint response contains some top level items to help you determine if you're getting correct data back from the API.

Properties

Name
location
Type
string
Description
A string indicating the name of the location you entered. We do our best to pick a local name that is familiar to the user, but in rare cases we can't determine a better display string and fall back to the location input.
Name
lowAccuracy
Type
bool
Description
Important: some location inputs can produce low-accuracy locations that may map to multiple Congressional districts. If lowAccuracy is set, this may be the case and we have selected the closest Congressional district for you. This is very likely if your only input is zip codes!
Name
state
Type
string
Description
The two-letter abbreviation for the state, district or territory.
Name
district
Type
string
Description
A string indicating the Congressional district number where the input is located. 0 for at-large states or territories.

Contact model

If you've passed your location correctly you'll get a list of contacts for your location with their associated information.

Properties

Name
id
Type
string
Description
A unique identifier for this contact. These will be Bioguide IDs for federal representatives, otherwise these are a UUID.
Name
name
Type
string
Description
The full name of this contact.
Name
phone
Type
string
Description
A phone number in 123-456-7890 format for the primary office for this contact.
Name
url
Type
string
Description
A URL for the official website of the contact if available.
Name
photoURL
Type
string
Description
A URL to a square 256x256 image for this contact. Typically an official portrait.
Name
party
Type
string
Description
A string indicating the party that the contact belongs to.
Name
state
Type
string
Description
The two-letter abbreviation for the state, district or territory the contact represents.
Name
district
Type
string
Description
A string-represented district number that the contact represents. 0 for at-large states or territories, or omitted when not applicable (such as Senate).
Name
reason
Type
string
Description
An english string indicating why you're seeing this contact.
Name
area
Type
string
Description
The office area for this contact. One of:
- US House
- US Senate
- StateUpper
- StateLower
- Governor
- SecState
Name
field_offices
Type
string
Description
An array of local office numbers and locations if available.

Error responses

If you pass an invalid location string that cannot be located

Name
error
Type
string
Description
An error string indicating what is wrong with the passed location. One of:
- no results from geocode: the location string is an invalid format
- point not found: the location string was valid but not within our coverage area (the United States and territories)

GET/v1/representatives

Representatives for a location

This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page.

Required attributes

Name
location
Type
string
Description
A location to look up representatives for. We support these location types:
- Zip code i.e. 94110
- Zip+4 i.e. 94110+3906
- Latitude and longitude i.e. 37.7455558,-122.4127467
- Full address i.e. 3200 24th St, San Francisco, CA
- Cross streets i.e. 24th and Noe St, San Francisco, CA

Optional attributes

Name
areas
Type
string
Description
Return only the representatives from these areas. Possible values are:
- US House
- US Senate

Request

GET

/v1/representatives

curl -G https://api.5calls.org/v1/representatives?location=94110 \
  -H "X-5Calls-Token: {token}"

Response

{
  "location": "San Francisco",
  "lowAccuracy": false,
  "state": "CA",
  "district": "11",
  "representatives": [
    {
      "id": "P000197",
      "name": "Nancy Pelosi",
      "phone": "202-225-4965",
      "photoURL": "https://images.5calls.org/house/256/P000197.jpg",
      "party": "Democrat",
      "state": "CA",
      "reason": "This is your representative in the House.",
      "area": "US House",
      "field_offices": [
        {
          "phone": "415-556-4862",
          "city": "San Francisco"
        }
      ]
    },
    {
      "id": "P000145",
      "name": "Alex Padilla",
      "phone": "202-224-3553",
      ],
      ...
    }
  ]
}