Office

A seat that lasts across elections and redistricting: a U.S. House seat, a governorship, a numbered council position, an at-large board.

Show samples as

The sample at the end of the page as JSON, or as CSV (format=csv).

Returned by: GET /v1/offices, GET /v1/offices/{slug}
Shapes: The full record is in GET /v1/offices/{slug}. The shorter forms in GET /v1/offices leave some fields out; a field that isn’t in every form says where it is.

How it connects

slug never changes. A contest names the seat it fills in seat.slug; its terms are in GET /v1/office-terms?offices={slug}.
districts lists every version of the seat’s district: lines used before 2022 redistricting have plan "2020". Each district_id is a contest district, so contests on either set of lines lead to the same office.
An at-large body elected together (a school board voting for 3 of 7) is one office with seats = 7; each contest says how many seats it filled.

Good to know

Holders are kept from January 1, 2020 on, and for seats we have results, from the 2018 elections.
current_holders is empty while a seat is vacant or before its holder is loaded.
Redistricting doesn’t make a new office; a seat created or eliminated by reapportionment has established_on or abolished_on.

Fields

Field	Type	Meaning	Example
`slug`	string	Permanent id of the seat: it stays the same across elections and redistricting.	`us-house-ca-12`
`name`	string	The seat’s name.	`U.S. Representative, California Congressional District 12`
`office_type`	string	The office, normalized across states.51 values: meanings	`us_representative`
`level`	string	federal, state or local.`federal`, `state`, `local` meanings	`federal`
`branch`	stringor null	executive, legislative or judicial.`executive`, `legislative`, `judicial` meanings	`legislative`
`state`	stringor nullTwo capital letters (USPS code)	USPS state code.	`CA`
`jurisdiction_ocd_id`	string	The division the seat belongs to, without a redistricting plan.	`ocd-division/country:us/state:ca/cd:12`
`seat_label`	stringor null	What tells the seat apart from others of its type in the same place: “Class 3”, “Position 8”, “Department 12”.	—
`seats`	integer	Members elected through this office: 1, or the size of an at-large body.	`1`
`term_years`	integeror null	Length of a full term in years.	`2`
`partisan`	booleanor null	Candidates run with party labels; null when not set.	`true`
`established_on`	stringor nullYYYY-MM-DD	When the seat was created, if after 2018.	—
`abolished_on`	stringor nullYYYY-MM-DD	When the seat stopped existing.	—
`successor`	stringor null	Slug of the seat that replaced it, when it was renumbered or merged.	—
`districts`	array of object	Every version of the seat’s district, oldest first.	—
`districts[].ocd_id`	string	OCD division id of this version of the district (“…/plan:2020” for lines used before 2022 redistricting).	`ocd-division/country:us/state:ca/cd:12/plan:2020`
`districts[].district_id`	integeror null	The contest district id (GET /v1/contests districts), where we have it.	`89100`
`districts[].plan`	stringor null	The redistricting plan these lines belong to, such as "2020"; null for current lines.	`2020`
`districts[].valid_from`	stringor nullYYYY-MM-DD	First day officials elected on these lines served.	—
`districts[].valid_to`	stringor nullYYYY-MM-DD	Last day they served.	—
`current_holders`	array of Office term	Who holds it now (empty while vacant or not known).	—
`updated_at`	stringISO 8601 date and time with time zone	When we last changed this record.	`2026-11-14T03:18:48.310841+00:00`
`terms`	array of Office term	Every term we have, oldest first.Only in GET /v1/offices/{slug}.	—
`contests`	array of object	Every contest for the seat we have, oldest first.Only in GET /v1/offices/{slug}.	—
`contests[].id`	integer	Contest id.Only in GET /v1/offices/{slug}.	`218514`
`contests[].title`	string	Title as printed.Only in GET /v1/offices/{slug}.	`United States Representative, District 12`
`contests[].election`	string	Election slug.Only in GET /v1/offices/{slug}.	`ca-2018-11-06-general`
`contests[].election_date`	stringYYYY-MM-DD	Election day.Only in GET /v1/offices/{slug}.	`2018-11-06`
`contests[].race_type`	string	regular, special, recall or retention.`regular`, `special`, `recall`, `retention` meaningsOnly in GET /v1/offices/{slug}.	`regular`
`contests[].stage`	string	general, primary or runoff.`general`, `primary`, `runoff` meaningsOnly in GET /v1/offices/{slug}.	`general`
`contests[].seats_up`	integer	Members this contest elects.Only in GET /v1/offices/{slug}.	`1`
`contests[].result_status`	stringor null	The result’s status, once there is one.`unofficial`, `certified` meaningsOnly in GET /v1/offices/{slug}.	`certified`
`contests[].seat_change`	Seat changeor null	Whether the seat changed hands; null for primaries and undecided contests.Only in GET /v1/offices/{slug}.	—

Download every dictionary as CSV or JSON.

CSV: `GET /v1/offices?format=csv`

One row per office (seat). District versions and current holders are joined with "; ". An empty cell is a null or a value that doesn’t apply. The next page’s cursor comes in the X-Next-Cursor header.

Column	Type	Meaning	Example
`slug`	string	Permanent id of the seat: it stays the same across elections and redistricting.From slug in the JSON.	`us-house-ca-12`
`name`	string	The seat’s name.From name in the JSON.	`U.S. Representative, California Congressional District 12`
`office_type`	string	The office, normalized across states.51 values: meaningsFrom office_type in the JSON.	`us_representative`
`level`	string	federal, state or local.`federal`, `state`, `local` meaningsFrom level in the JSON.	`federal`
`branch`	stringcan be empty	executive, legislative or judicial.`executive`, `legislative`, `judicial` meaningsFrom branch in the JSON.	`legislative`
`state`	stringcan be emptyTwo capital letters (USPS code)	USPS state code.From state in the JSON.	`CA`
`jurisdiction_ocd_id`	string	The division the seat belongs to, without a redistricting plan.From jurisdiction_ocd_id in the JSON.	`ocd-division/country:us/state:ca/cd:12`
`seat_label`	stringcan be empty	What tells the seat apart from others of its type in the same place: “Class 3”, “Position 8”, “Department 12”.From seat_label in the JSON.	—
`seats`	integer	Members elected through this office: 1, or the size of an at-large body.From seats in the JSON.	`1`
`term_years`	integercan be empty	Length of a full term in years.From term_years in the JSON.	`2`
`partisan`	booleancan be empty	Candidates run with party labels; null when not set.From partisan in the JSON.	`true`
`established_on`	stringcan be emptyYYYY-MM-DD	When the seat was created, if after 2018.From established_on in the JSON.	—
`abolished_on`	stringcan be emptyYYYY-MM-DD	When the seat stopped existing.From abolished_on in the JSON.	—
`successor`	stringcan be empty	Slug of the seat that replaced it, when it was renumbered or merged.From successor in the JSON.	—
`district_ocd_ids`	stringcan be emptyvalues joined with "; "	OCD division id of this version of the district (“…/plan:2020” for lines used before 2022 redistricting).From districts[].ocd_id in the JSON.	`ocd-division/country:us/state:ca/cd:12/plan:2020; ocd-division/country:us/state:ca/cd:12/…`
`district_plans`	stringcan be emptyvalues joined with "; "	The redistricting plan these lines belong to, such as "2020"; null for current lines.From districts[].plan in the JSON.	`2020; 2024`
`current_holders`	stringcan be emptyvalues joined with "; "	The holder’s name as the source gives it.From current_holders[].name in the JSON.	`Lateefah Simon`
`current_holder_parties`	stringcan be emptyvalues joined with "; "	Party when the term began.From current_holders[].party in the JSON.	`Democratic`
`updated_at`	stringISO 8601 date and time with time zone	When we last changed this record.From updated_at in the JSON.	`2026-11-14T03:18:48.310841+00:00`

Sample (JSON)

One office as the API returns it, in GET /v1/offices/{slug}. More in the sample data.

{
  "name": "U.S. Representative, California Congressional District 12",
  "slug": "us-house-ca-12",
  "level": "federal",
  "seats": 1,
  "state": "CA",
  "terms": [
    {
      "id": 24,
      "how": "elected",
      "name": "Nancy Pelosi",
      "party": "Democratic",
      "state": "CA",
      "office": "us-house-ca-12",
      "source": {
        "url": "https://www.fec.gov/resources/cms-content/documents/federalelections2018.xlsx",
        "kind": "results",
        "name": "Federal Election Commission, Federal Elections 2018 (official results)",
        "license": null,
        "retrieved_on": null
      },
      "end_date": "2021-01-03",
      "contest_id": 218514,
      "end_reason": "term_ended",
      "person_key": "name:ca:pelosi-nancy",
      "start_date": "2019-01-03",
      "updated_at": "2026-11-14T03:18:48.42618+00:00",
      "bioguide_id": null,
      "dates_basis": "statutory",
      "district_id": 89100,
      "office_name": "U.S. Representative, California Congressional District 12",
      "candidate_id": 73180,
      "election_date": "2018-11-06",
      "party_changes": [],
      "district_ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2020",
      "scheduled_end_date": "2021-01-03",
      "openstates_person_id": null
    },
    {
      "id": 23,
      "how": "elected",
      "name": "Nancy Pelosi",
      "party": "Democratic",
      "state": "CA",
      "office": "us-house-ca-12",
      "source": {
        "url": "https://www.fec.gov/resources/cms-content/documents/federalelections2020.xlsx",
        "kind": "results",
        "name": "Federal Election Commission, Federal Elections 2020 (official results)",
        "license": null,
        "retrieved_on": null
      },
      "end_date": "2023-01-03",
      "contest_id": 109058,
      "end_reason": "term_ended",
      "person_key": "name:ca:pelosi-nancy",
      "start_date": "2021-01-03",
      "updated_at": "2026-11-14T03:18:48.42618+00:00",
      "bioguide_id": null,
      "dates_basis": "statutory",
      "district_id": 89100,
      "office_name": "U.S. Representative, California Congressional District 12",
      "candidate_id": 73180,
      "election_date": "2020-11-03",
      "party_changes": [],
      "district_ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2020",
      "scheduled_end_date": "2023-01-03",
      "openstates_person_id": null
    },
    {
      "id": 129,
      "how": "elected",
      "name": "Barbara Lee",
      "party": "Democratic",
      "state": "CA",
      "office": "us-house-ca-12",
      "source": {
        "url": "https://www.fec.gov/documents/5676/federalelections2022.xlsx",
        "kind": "results",
        "name": "Federal Election Commission, Federal Elections 2022 (official results)",
        "license": null,
        "retrieved_on": null
      },
      "end_date": "2025-01-03",
      "contest_id": 77336,
      "end_reason": "term_ended",
      "person_key": "name:ca:lee-barbara",
      "start_date": "2023-01-03",
      "updated_at": "2026-11-14T03:18:48.42618+00:00",
      "bioguide_id": null,
      "dates_basis": "statutory",
      "district_id": 74343,
      "office_name": "U.S. Representative, California Congressional District 12",
      "candidate_id": 122059,
      "election_date": "2022-11-08",
      "party_changes": [],
      "district_ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2024",
      "scheduled_end_date": "2025-01-03",
      "openstates_person_id": null
    },
    {
      "id": 130,
      "how": "elected",
      "name": "Lateefah Simon",
      "party": "Democratic",
      "state": "CA",
      "office": "us-house-ca-12",
      "source": {
        "url": "https://dataverse.harvard.edu/file.xhtml?fileId=13731130",
        "kind": "results",
        "name": "MIT Election Data and Science Lab, from official returns",
        "license": null,
        "retrieved_on": null
      },
      "end_date": null,
      "contest_id": 43982,
      "end_reason": null,
      "person_key": "bioguide:S001231",
      "start_date": "2025-01-03",
      "updated_at": "2026-11-14T03:18:48.405919+00:00",
      "bioguide_id": "S001231",
      "dates_basis": "statutory",
      "district_id": 74343,
      "office_name": "U.S. Representative, California Congressional District 12",
      "candidate_id": 83,
      "election_date": "2024-11-05",
      "party_changes": [],
      "district_ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2024",
      "scheduled_end_date": "2027-01-03",
      "openstates_person_id": null
    }
  ],
  "branch": "legislative",
  "contests": [
    {
      "id": 218514,
      "stage": "general",
      "title": "United States Representative, District 12",
      "election": "ca-2018-11-06-general",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": {
        "office": "us-house-ca-12",
        "flipped": null,
        "outcome": "unknown",
        "partisan": true,
        "open_seats": 0,
        "vacant_since": null,
        "incumbents_up": 0,
        "winner_parties": [
          "Democratic"
        ],
        "holders_going_in": [],
        "parties_going_in": [],
        "incumbents_defeated": 0,
        "incumbents_reelected": 0
      },
      "election_date": "2018-11-06",
      "result_status": "certified"
    },
    {
      "id": 109058,
      "stage": "general",
      "title": "United States Representative, District 12",
      "election": "ca-2020-11-03-general",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": {
        "office": "us-house-ca-12",
        "flipped": false,
        "outcome": "incumbent_reelected",
        "partisan": true,
        "open_seats": 0,
        "vacant_since": null,
        "incumbents_up": 1,
        "winner_parties": [
          "Democratic"
        ],
        "holders_going_in": [
          {
            "how": "elected",
            "name": "Nancy Pelosi",
            "party": "Democratic",
            "start_date": "2019-01-03"
          }
        ],
        "parties_going_in": [
          "Democratic"
        ],
        "incumbents_defeated": 0,
        "incumbents_reelected": 1
      },
      "election_date": "2020-11-03",
      "result_status": "certified"
    },
    {
      "id": 172979,
      "stage": "primary",
      "title": "United States Representative, District 12",
      "election": "ca-2022-06-07-primary",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": null,
      "election_date": "2022-06-07",
      "result_status": "certified"
    },
    {
      "id": 77336,
      "stage": "general",
      "title": "United States Representative, District 12",
      "election": "ca-2022-11-08-general",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": {
        "office": "us-house-ca-12",
        "flipped": false,
        "outcome": "open_seat",
        "partisan": true,
        "open_seats": 1,
        "vacant_since": null,
        "incumbents_up": 1,
        "winner_parties": [
          "Democratic"
        ],
        "holders_going_in": [
          {
            "how": "elected",
            "name": "Nancy Pelosi",
            "party": "Democratic",
            "start_date": "2021-01-03"
          }
        ],
        "parties_going_in": [
          "Democratic"
        ],
        "incumbents_defeated": 0,
        "incumbents_reelected": 0
      },
      "election_date": "2022-11-08",
      "result_status": "certified"
    },
    {
      "id": 164838,
      "stage": "primary",
      "title": "U.S. Representative, District 12",
      "election": "ca-2024-03-05-primary",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": null,
      "election_date": "2024-03-05",
      "result_status": "certified"
    },
    {
      "id": 43982,
      "stage": "general",
      "title": "United States Representative, District 12",
      "election": "ca-2024-11-05-general",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": {
        "office": "us-house-ca-12",
        "flipped": false,
        "outcome": "open_seat",
        "partisan": true,
        "open_seats": 1,
        "vacant_since": null,
        "incumbents_up": 1,
        "winner_parties": [
          "Democratic"
        ],
        "holders_going_in": [
          {
            "how": "elected",
            "name": "Barbara Lee",
            "party": "Democratic",
            "start_date": "2023-01-03"
          }
        ],
        "parties_going_in": [
          "Democratic"
        ],
        "incumbents_defeated": 0,
        "incumbents_reelected": 0
      },
      "election_date": "2024-11-05",
      "result_status": "certified"
    },
    {
      "id": 149383,
      "stage": "primary",
      "title": "U.S. Representative, District 12",
      "election": "ca-2026-06-02-primary",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": null,
      "election_date": "2026-06-02",
      "result_status": "certified"
    },
    {
      "id": 178,
      "stage": "general",
      "title": "United States Representative, District 12",
      "election": "ca-2026-11-03-general",
      "seats_up": 1,
      "race_type": "regular",
      "seat_change": null,
      "election_date": "2026-11-03",
      "result_status": "unofficial"
    }
  ],
  "partisan": true,
  "districts": [
    {
      "plan": "2020",
      "ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2020",
      "valid_to": null,
      "valid_from": null,
      "district_id": 89100
    },
    {
      "plan": "2024",
      "ocd_id": "ocd-division/country:us/state:ca/cd:12/plan:2024",
      "valid_to": null,
      "valid_from": null,
      "district_id": 74343
    },
    {
      "plan": null,
      "ocd_id": "ocd-division/country:us/state:ca/cd:12",
      "valid_to": null,
      "valid_from": null,
      "district_id": 24
    }
  ],
  "successor": null,
  "seat_label": null,
  "term_years": 2,
  "updated_at": "2026-11-14T03:18:48.310841+00:00",
  "office_type": "us_representative",
  "abolished_on": null,
  "established_on": null,
  "current_holders": [
    {
      "how": "elected",
      "name": "Lateefah Simon",
      "party": "Democratic",
      "person_key": "bioguide:S001231",
      "start_date": "2025-01-03",
      "scheduled_end_date": "2027-01-03"
    }
  ],
  "jurisdiction_ocd_id": "ocd-division/country:us/state:ca/cd:12"
}

Sample (CSV)

The same records as the JSON sample, as GET /v1/offices?format=csv returns them. Download: CSV, JSON.

slug,name,office_type,level,branch,state,jurisdiction_ocd_id,seat_label,seats,term_years,partisan,established_on,abolished_on,successor,district_ocd_ids,district_plans,current_holders,current_holder_parties,updated_at
us-house-ca-12,"U.S. Representative, California Congressional District 12",us_representative,federal,legislative,CA,ocd-division/country:us/state:ca/cd:12,,1,2,true,,,,ocd-division/country:us/state:ca/cd:12/plan:2020; ocd-division/country:us/state:ca/cd:12/plan:2024; ocd-division/country:us/state:ca/cd:12,2020; 2024,Lateefah Simon,Democratic,2026-11-14T03:18:48.310841+00:00
us-house-ca-22,"U.S. Representative, California Congressional District 22",us_representative,federal,legislative,CA,ocd-division/country:us/state:ca/cd:22,,1,2,true,,,,ocd-division/country:us/state:ca/cd:22/plan:2020; ocd-division/country:us/state:ca/cd:22/plan:2024; ocd-division/country:us/state:ca/cd:22,2020; 2024,David G. Valadao,Republican,2026-11-14T03:18:48.310841+00:00