{"openapi":"3.0.3","info":{"title":"Civic Lens API","version":"1.0.0","description":"# Civic Lens API\n\nEvery current US government officeholder in one REST API — federal, state and\nterritorial; legislative, executive and judicial. Verified, current, and\ntimestamped field by field.\n\n## What you get\n\n- **Complete coverage**: the U.S. House and Senate, every state legislature,\n  governors and statewide executives, and state high courts — all 50 states,\n  DC and the territories\n- **Verified records**: compiled from public sources, independently\n  cross-verified, and human-reviewed before publication\n- **Identity-verified photos**: every portrait passes an identity check and is\n  served from our own storage, so image links never rot\n- **Confirmed social accounts**: handles are published once independently\n  confirmed\n- **Clean responses**: every field present is verified data — absent values\n  are omitted, never sent as `null`\n- **Continuously refreshed**: federal records refresh weekly, every\n  jurisdiction is re-verified on a monthly cycle, and changes pass a human\n  approval queue before publication\n- **A live vacancy feed**: seats are vacated explicitly, with a reason and a\n  timestamp, so downstream products never have to infer a departure\n\n## Rate limiting\n\nRequests are currently unmetered. Metered plans with API keys are coming;\nexisting integrations will get a migration window before keys are required.\n\n## Support\n\nQuestions, bug reports, and feature requests: start at the documentation on\nthis site.","contact":{"name":"Civic Lens","url":"https://civiclens.io"},"license":{"name":"Commercial","url":"https://civiclens.io/pricing"}},"servers":[{"url":"https://civiclens.io/api/v1","description":"Production API"},{"url":"http://localhost:3002/api/v1","description":"Development server"}],"tags":[{"name":"government-members","description":"Government member endpoints organized by jurisdiction and role"},{"name":"members","description":"Cross-cutting member search and filtering"},{"name":"roles","description":"Government role definitions and metadata"},{"name":"statistics","description":"Aggregated statistics and counts"},{"name":"vacancies","description":"Currently-vacant legislative seats"},{"name":"spec","description":"The machine-readable API description"}],"paths":{"/governments/us/federal/{state}/legislature/current":{"get":{"tags":["government-members"],"summary":"Get a state’s full congressional delegation","description":"Returns both chambers at once — the state’s U.S. Representatives and Senators. Pass `congress` as the identifier to get every sitting member of Congress instead of one state’s delegation.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/federal/{state}/legislature/house/current":{"get":{"tags":["government-members"],"summary":"Get current U.S. House Representatives for a state","description":"Returns current members of the U.S. House of Representatives from a specific state.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/federal/{state}/legislature/senate/current":{"get":{"tags":["government-members"],"summary":"Get current U.S. Senators for a state","description":"Returns current U.S. Senators from a specific state (typically 2 senators per state).","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/legislature/current":{"get":{"tags":["government-members"],"summary":"Get a state’s full legislature","description":"Returns every sitting member of the state legislature — both chambers, or the single chamber in a unicameral state.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/legislature/upper/current":{"get":{"tags":["government-members"],"summary":"Get current state senate members","description":"Returns current members of the state senate (upper chamber) for a specific state.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/legislature/lower/current":{"get":{"tags":["government-members"],"summary":"Get current state house members","description":"Returns current members of the state house/assembly (lower chamber) for a specific state.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/legislature/unicameral/current":{"get":{"tags":["government-members"],"summary":"Get current unicameral legislature members","description":"Returns current members of a unicameral state legislature. Nebraska is the only state with one, so this returns an empty list for every other state rather than an error.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/executive/current":{"get":{"tags":["government-members"],"summary":"Get all current state executive officeholders","description":"Returns every executive-branch officeholder for a state — the governor, lieutenant governor, and other statewide offices.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/judicial/current":{"get":{"tags":["government-members"],"summary":"Get current state judicial officeholders","description":"Returns sitting justices of the state’s highest court, and appellate judges where they are tracked.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/governments/us/states/{state}/executive/governor/current":{"get":{"tags":["government-members"],"summary":"Get current state governor","description":"Returns the current governor for a specific state.","parameters":[{"$ref":"#/components/parameters/StateCodePath"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/members":{"get":{"tags":["members"],"summary":"Search government members","description":"Search and filter government members across all levels and jurisdictions with various criteria.","parameters":[{"$ref":"#/components/parameters/CountryQuery"},{"$ref":"#/components/parameters/StateQuery"},{"$ref":"#/components/parameters/RoleQuery"},{"$ref":"#/components/parameters/PartyQuery"},{"$ref":"#/components/parameters/ChamberQuery"},{"$ref":"#/components/parameters/LevelQuery"},{"$ref":"#/components/parameters/BranchQuery"},{"$ref":"#/components/parameters/DistrictQuery"},{"$ref":"#/components/parameters/SearchQuery"},{"$ref":"#/components/parameters/ActiveQuery"},{"$ref":"#/components/parameters/SortQuery"},{"$ref":"#/components/parameters/OrderQuery"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"$ref":"#/components/responses/MemberList"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/members/{id}":{"get":{"tags":["members"],"summary":"Get a single member","description":"Returns one member by `ocdPersonId` or by the internal record id. The `ocdPersonId` is the stable identifier and the one to store.","parameters":[{"$ref":"#/components/parameters/MemberIdPath"}],"responses":{"200":{"$ref":"#/components/responses/SingleMember"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/vacancies":{"get":{"tags":["vacancies"],"summary":"List currently-vacant legislative seats","description":"Seats whose holder has departed and which no sitting member currently occupies. Poll this to vacate seats explicitly rather than inferring a vacancy from a member disappearing between syncs.\n\nScope is legislative seats only — they are keyed by (state, chamber, district), which is what makes occupancy checkable. Executive and judicial departures are not reported here because their seats have no stable district key.","parameters":[{"$ref":"#/components/parameters/StateQuery"}],"responses":{"200":{"description":"Currently-vacant seats","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["vacancies","count"],"properties":{"vacancies":{"type":"array","items":{"$ref":"#/components/schemas/ApiVacancy"}},"count":{"type":"integer","minimum":0}}},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openapi.json":{"get":{"tags":["spec"],"summary":"Get this OpenAPI document","description":"Returns the machine-readable OpenAPI description of this API. Served with permissive CORS so external tooling can fetch it.","responses":{"200":{"description":"The OpenAPI document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/roles":{"get":{"tags":["roles"],"summary":"Get government role definitions","description":"Returns available government role definitions with metadata and filtering options.","parameters":[{"name":"level","in":"query","description":"Filter by government level","required":false,"schema":{"type":"string","enum":["federal","state","local"]}},{"name":"branch","in":"query","description":"Filter by government branch","required":false,"schema":{"type":"string","enum":["legislative","executive","judicial"]}},{"$ref":"#/components/parameters/ActiveQuery"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"List of government roles","content":{"application/json":{"schema":{"type":"object","required":["data","pagination","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiGovRole"}},"pagination":{"$ref":"#/components/schemas/ApiPagination"},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"examples":{"govRoles":{"$ref":"#/components/examples/govRoles"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/statistics":{"get":{"tags":["statistics"],"summary":"Get aggregated statistics","description":"Returns aggregated statistics about government members and roles.","parameters":[{"name":"type","in":"query","description":"Type of statistic to retrieve","required":false,"schema":{"type":"string","enum":["role_count","people_count"]}},{"name":"roleId","in":"query","description":"Role ID for role_count statistics","required":false,"schema":{"type":"string"},"example":"us-federal-house-member"},{"name":"level","in":"query","description":"Aggregate level for statistics","required":false,"schema":{"type":"string","enum":["global","federal","state","chamber","role"],"default":"global"}},{"name":"jurisdiction","in":"query","description":"Jurisdiction for statistics","required":false,"schema":{"type":"string","default":"us"}}],"responses":{"200":{"description":"Statistics data","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"description":"Summary statistics object"},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","format":"date-time"}}}}},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StatisticResponse"},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","format":"date-time"}}}}}]},"examples":{"roleCountStat":{"$ref":"#/components/examples/roleCountStat"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/statistics/health":{"get":{"tags":["statistics"],"summary":"API health statistics","description":"Returns health and performance statistics for the API.","responses":{"200":{"description":"API health statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"uptime":{"type":"number","description":"Uptime in seconds"},"lastUpdate":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/statistics/overview":{"get":{"tags":["statistics"],"summary":"Statistics overview","description":"Returns an overview of key statistics across all government levels.","responses":{"200":{"description":"Statistics overview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"federal":{"type":"object","properties":{"house":{"type":"integer"},"senate":{"type":"integer"},"total":{"type":"integer"}}},"states":{"type":"object","properties":{"legislators":{"type":"integer"},"governors":{"type":"integer"},"total":{"type":"integer"}}},"grandTotal":{"type":"integer"}}},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","format":"date-time"}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"ApiGovernment":{"type":"object","required":["country","level","branch"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code, lowercase. \"us\" covers US federal, state and local officials.","example":"us","pattern":"^[a-z]{2}$"},"level":{"type":"string","enum":["federal","state","local","national"],"description":"Government level. \"federal\", \"state\" and \"local\" are US; \"national\" is the national government of another country, kept separate so existing level=federal queries are unaffected by international data."},"branch":{"type":"string","enum":["legislative","executive","judicial"],"description":"Government branch"},"stateCode":{"type":"string","description":"State code for federal and state levels (e.g., \"ca\", \"tx\", \"ny\")","example":"ca","pattern":"^[a-z]{2}$"},"chamber":{"type":"string","enum":["upper","lower","unicameral"],"description":"Legislative chamber (for legislative branch)"},"district":{"type":"string","description":"District number or identifier","example":"12"},"termStart":{"type":"string","format":"date","description":"Term start date (ISO 8601 date)","example":"2023-01-03"},"termEnd":{"type":"string","format":"date","description":"Term end date (ISO 8601 date)","example":"2025-01-03"}}},"ApiContact":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Official email address","example":"representative@house.gov"},"phone":{"type":"string","description":"Official phone number","example":"(202) 225-1234"},"website":{"type":"string","format":"uri","description":"Official website URL","example":"https://example.house.gov"},"districtOffices":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"Office address","example":"123 Main Street, Anytown, CA 12345"},"phone":{"type":"string","description":"Office phone number","example":"(555) 123-4567"},"fax":{"type":"string","description":"Office fax number","example":"(555) 123-4568"}}},"description":"District office locations"},"capitolOffice":{"type":"object","properties":{"address":{"type":"string","description":"Capitol office address","example":"1234 Longworth House Office Building, Washington, DC 20515"},"phone":{"type":"string","description":"Capitol office phone number","example":"(202) 225-1234"},"fax":{"type":"string","description":"Capitol office fax number","example":"(202) 225-5678"}},"description":"Capitol office information"}}},"ApiSocialMedia":{"type":"object","properties":{"twitter":{"type":"string","description":"Twitter/X profile URL","example":"https://twitter.com/representative"},"facebook":{"type":"string","description":"Facebook profile URL","example":"https://facebook.com/representative"},"instagram":{"type":"string","description":"Instagram profile URL","example":"https://instagram.com/representative"},"youtube":{"type":"string","description":"YouTube channel URL","example":"https://youtube.com/representative"}}},"ApiMember":{"type":"object","description":"A government member. IMPORTANT: fields with no value are OMITTED from the response rather than returned as null, so a field you do not see in one record may still exist and be populated on others — inspect a full page, or this schema, rather than a single record. Coverage varies by field and by state. Two fields are additionally gated: `profileImage` is only served once the photo is verified AND hosted in our own store, and `socialMedia` only once the handles are cross-checked against a curated source.","required":["id","name","government","addedToRole","updatedAt"],"properties":{"id":{"type":"string","description":"Unique member identifier","example":"person-123"},"bioGuideId":{"type":"string","description":"Congressional Biographical Directory ID","example":"A000001"},"ocdPersonId":{"type":"string","description":"Open Civic Data person identifier","example":"ocd-person/12345678-1234-1234-1234-123456789012"},"name":{"type":"string","description":"Full name of the government member","example":"John A. Smith"},"title":{"type":"string","description":"Official title","example":"Representative"},"firstName":{"type":"string","description":"Given name","example":"John"},"lastName":{"type":"string","description":"Family name","example":"Smith"},"profileImage":{"type":"string","format":"uri","description":"Identity-verified portrait, served from our own storage. Present only when both conditions hold — a photo we could not verify, or one we do not host, is omitted rather than linked.","example":"https://abc123.public.blob.vercel-storage.com/members/jane-doe.jpg"},"religion":{"type":"string","description":"Religious affiliation (if publicly disclosed)","example":"Methodist"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth (ISO 8601 date)","example":"1960-05-15"},"birthPlace":{"type":"string","description":"Place of birth, as published by the official source","example":"Pittsburgh, PA"},"gender":{"type":"string","description":"Gender, where the source publishes it","example":"Female"},"bio":{"type":"string","description":"Biographical prose, compiled from public records. Election-cycle text (\"is running for re-election\", ballot and primary dates) is stripped, so the text does not go stale between cycles.","example":"Jodi Salvo was born in Pittsburgh, Pennsylvania. Salvo earned a bachelor’s degree from the California University of Pennsylvania in 1991…"},"education":{"type":"array","items":{"type":"string"},"description":"Schools attended, with degree and year where published","example":["Boston College, B.A., 1972","Suffolk University Law School"]},"profession":{"type":"array","items":{"type":"string"},"description":"Occupations held, as published by the official source","example":["Attorney","Farmer"]},"family":{"type":"string","description":"Marital status and relative COUNTS only. Names of relatives are deliberately never published — official pages go stale, and a named spouse or child identifies someone who is not the officeholder. There are no separate spouse/children/grandchildren fields for the same reason.","example":"Married; five children, eight grandchildren."},"government":{"$ref":"#/components/schemas/ApiGovernment"},"party":{"type":"string","description":"Political party affiliation","example":"Democratic"},"contactInfo":{"$ref":"#/components/schemas/ApiContact"},"socialMedia":{"$ref":"#/components/schemas/ApiSocialMedia"},"personalWebsite":{"type":"string","format":"uri","description":"Personal or campaign website","example":"https://example.com"},"sourceUrl":{"type":"string","format":"uri","description":"The page this member’s enrichment was derived from","example":"https://ohiohouse.gov/members/jodi-salvo/biography"},"appointedBy":{"type":"string","description":"For appointed offices, who made the appointment. Absent for elected members.","example":"Greg Abbott"},"addedToRole":{"type":"integer","description":"Unix timestamp when added to current role","example":1672531200},"updatedAt":{"type":"integer","description":"Unix timestamp of last update","example":1672531200}}},"ApiPagination":{"type":"object","required":["page","limit","total","hasMore"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number","example":1},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Number of items per page","example":50},"total":{"type":"integer","minimum":0,"description":"Total number of items","example":435},"hasMore":{"type":"boolean","description":"Whether there are more pages available","example":true},"nextCursor":{"type":"string","description":"Cursor for next page (if applicable)","example":"eyJwYWdlIjoyLCJsaW1pdCI6NTB9"}}},"ApiMeta":{"type":"object","required":["lastUpdated"],"properties":{"government":{"$ref":"#/components/schemas/ApiGovernment"},"lastUpdated":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when data was last updated","example":"2024-01-15T10:30:00Z"},"filters":{"type":"object","additionalProperties":true,"description":"Applied filters for the request","example":{"state":"ca","party":"Democratic","active":true}}}},"ApiListResponse":{"type":"object","required":["data","pagination","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiMember"},"description":"Array of government members"},"pagination":{"$ref":"#/components/schemas/ApiPagination"},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ApiResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ApiMember"},"meta":{"type":"object","required":["lastUpdated"],"properties":{"lastUpdated":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when data was last updated","example":"2024-01-15T10:30:00Z"}}}}},"ApiGovRole":{"type":"object","required":["id","name","level","active","government"],"properties":{"id":{"type":"string","description":"Unique role identifier","example":"us-federal-house-member"},"name":{"type":"string","description":"Human-readable role name","example":"U.S. House Representative"},"level":{"type":"string","enum":["federal","state","local","national"],"description":"Government level. `national` is the national government of a country other than the US, deliberately distinct from `federal`."},"chamber":{"type":"string","enum":["upper","lower"],"description":"Legislative chamber (for legislative roles). Omitted for unicameral legislatures — the role name carries the distinction."},"memberCount":{"type":"integer","minimum":0,"description":"Number of sitting members currently holding this role","example":38},"description":{"type":"string","description":"Detailed role description","example":"Members of the U.S. House of Representatives serve two-year terms representing the people of a specific congressional district."},"active":{"type":"boolean","description":"Whether this role is currently active","example":true},"government":{"type":"object","required":["country","level","branch"],"properties":{"country":{"type":"string","example":"us"},"level":{"type":"string","enum":["federal","state","local","national"]},"branch":{"type":"string","enum":["legislative","executive","judicial"]},"stateCode":{"type":"string","pattern":"^[a-z]{2}$","example":"ca"}}}}},"ApiVacancy":{"type":"object","required":["stateCode","level","branch","chamber","district","formerMember","vacatedAt","reason"],"properties":{"stateCode":{"type":"string","pattern":"^[a-z]{2}$","example":"tx"},"level":{"type":"string","enum":["federal","state","local","national"]},"branch":{"type":"string","enum":["legislative"],"description":"Always `legislative` — see the endpoint description."},"chamber":{"type":"string","enum":["upper","lower","unicameral"]},"district":{"type":"string","description":"District identifier of the vacant seat","example":"30"},"formerMember":{"type":"string","description":"Name of the member who held the seat","example":"Jane Doe"},"vacatedAt":{"type":"string","format":"date-time","description":"When the seat was recorded as vacated"},"reason":{"type":"string","enum":["lost_election","resigned","deceased","term_ended","other"]}}},"ApiError":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Error code identifier","example":"INVALID_PARAMETER"},"message":{"type":"string","description":"Human-readable error message","example":"Invalid parameter value provided"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details","example":{"parameter":"state","providedValue":"invalid","allowedValues":["ca","tx","ny"]}}}},"meta":{"type":"object","required":["timestamp","path"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when error occurred","example":"2024-01-15T10:30:00Z"},"path":{"type":"string","description":"API path where error occurred","example":"/api/v1/members"}}}}},"StatisticResponse":{"type":"object","required":["type","queryId","jurisdiction","count","lastUpdated"],"properties":{"type":{"type":"string","enum":["role_count","people_count"],"description":"Type of statistic","example":"role_count"},"queryId":{"type":"string","description":"Query identifier for the statistic","example":"us-federal-house-member"},"jurisdiction":{"type":"string","description":"Jurisdiction for the statistic","example":"us"},"count":{"type":"integer","minimum":0,"description":"Count value","example":435},"lastUpdated":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of last update","example":"2024-01-15T10:30:00Z"}}}},"examples":{"houseRepresentative":{"summary":"U.S. House Representative","value":{"id":"person-A000374","bioGuideId":"A000374","ocdPersonId":"ocd-person/f4a12345-6789-4abc-def0-123456789abc","name":"Ralph Abraham","title":"Representative","profileImage":"https://abc123.public.blob.vercel-storage.com/members/ralph-abraham.jpg","religion":"Baptist","family":"Married; three children, eight grandchildren.","education":["Louisiana State University, D.V.M.","LSU School of Medicine, M.D."],"profession":["Physician","Veterinarian"],"bio":"Ralph Abraham is a physician and veterinarian who represented Louisiana in the U.S. House.","dateOfBirth":"1954-09-16","government":{"country":"us","level":"federal","branch":"legislative","stateCode":"la","chamber":"lower","district":"5","termStart":"2023-01-03","termEnd":"2025-01-03"},"party":"Republican","contactInfo":{"email":"contact@abraham.house.gov","phone":"(202) 225-8490","website":"https://abraham.house.gov","capitolOffice":{"address":"417 Cannon House Office Building, Washington, DC 20515","phone":"(202) 225-8490","fax":"(202) 225-5639"},"districtOffices":[{"address":"2003 MacArthur Drive, Suite A, Alexandria, LA 71301","phone":"(318) 445-0818","fax":"(318) 445-3776"},{"address":"1412 Centre Court, Suite 402, Monroe, LA 71201","phone":"(318) 322-3500","fax":"(318) 322-3542"}]},"socialMedia":{"twitter":"https://twitter.com/RepAbraham","facebook":"https://facebook.com/RepRalphAbraham","youtube":"https://youtube.com/RepRalphAbraham"},"addedToRole":1672531200,"updatedAt":1705046400}},"senator":{"summary":"U.S. Senator","value":{"id":"person-A000360","bioGuideId":"A000360","ocdPersonId":"ocd-person/a1b2c345-d678-9ef0-1234-56789abcdef0","name":"Lamar Alexander","title":"Senator","profileImage":"https://abc123.public.blob.vercel-storage.com/members/lamar-alexander.jpg","religion":"Presbyterian","dateOfBirth":"1940-07-03","government":{"country":"us","level":"federal","branch":"legislative","stateCode":"tn","chamber":"upper","termStart":"2021-01-03","termEnd":"2027-01-03"},"party":"Republican","contactInfo":{"email":"contact@alexander.senate.gov","phone":"(202) 224-4944","website":"https://alexander.senate.gov","capitolOffice":{"address":"455 Dirksen Senate Office Building, Washington, DC 20510","phone":"(202) 224-4944","fax":"(202) 228-3398"},"districtOffices":[{"address":"3322 West End Avenue, Suite 120, Nashville, TN 37203","phone":"(615) 736-5129","fax":"(615) 269-4803"},{"address":"800 Market Street, Suite 112, Knoxville, TN 37902","phone":"(865) 545-4253","fax":"(865) 545-4252"}]},"socialMedia":{"twitter":"https://twitter.com/SenAlexander","facebook":"https://facebook.com/SenatorLamarAlexander"},"addedToRole":1672531200,"updatedAt":1705046400}},"stateRepresentative":{"summary":"State House Representative","value":{"id":"person-ca-assembly-001","ocdPersonId":"ocd-person/ca12345-6789-abcd-ef01-23456789abcd","name":"Patricia C. Bates","title":"Assembly Member","government":{"country":"us","level":"state","branch":"legislative","stateCode":"ca","chamber":"lower","district":"73","termStart":"2022-12-05","termEnd":"2024-11-30"},"party":"Republican","contactInfo":{"phone":"(916) 319-2073","website":"https://assembly.ca.gov/assemblymember/bates","capitolOffice":{"address":"State Capitol, Room 3104, Sacramento, CA 95814","phone":"(916) 319-2073","fax":"(916) 319-2173"},"districtOffices":[{"address":"33282 Golden Lantern, Suite 103, Dana Point, CA 92629","phone":"(949) 496-1067","fax":"(949) 496-1068"}]},"addedToRole":1670198400,"updatedAt":1705046400}},"governor":{"summary":"State Governor","value":{"id":"person-ca-governor-001","ocdPersonId":"ocd-person/gov12345-6789-abcd-ef01-23456789abcd","name":"Gavin Newsom","title":"Governor","government":{"country":"us","level":"state","branch":"executive","stateCode":"ca","termStart":"2019-01-07","termEnd":"2027-01-02"},"party":"Democratic","contactInfo":{"phone":"(916) 445-2841","website":"https://gov.ca.gov","capitolOffice":{"address":"Governor's Office, State Capitol Building, Sacramento, CA 95814","phone":"(916) 445-2841"}},"socialMedia":{"twitter":"https://twitter.com/GavinNewsom","facebook":"https://facebook.com/GavinNewsom","instagram":"https://instagram.com/gavinnewsom"},"addedToRole":1546819200,"updatedAt":1705046400}},"houseMembers":{"summary":"List of House Representatives","value":{"data":[{"id":"person-A000374","bioGuideId":"A000374","name":"Ralph Abraham","title":"Representative","government":{"country":"us","level":"federal","branch":"legislative","stateCode":"la","chamber":"lower","district":"5"},"party":"Republican","addedToRole":1672531200,"updatedAt":1705046400},{"id":"person-A000375","bioGuideId":"A000375","name":"Alma Adams","title":"Representative","government":{"country":"us","level":"federal","branch":"legislative","stateCode":"nc","chamber":"lower","district":"12"},"party":"Democratic","addedToRole":1672531200,"updatedAt":1705046400}],"pagination":{"page":1,"limit":50,"total":435,"hasMore":true},"meta":{"government":{"country":"us","level":"federal","branch":"legislative","chamber":"lower"},"lastUpdated":"2024-01-15T10:30:00Z"}}},"invalidParameter":{"summary":"Invalid Parameter Error","value":{"error":{"code":"INVALID_PARAMETER","message":"Invalid state code provided","details":{"parameter":"state","providedValue":"xx","allowedPattern":"^[a-z]{2}$","examples":["ca","tx","ny"]}},"meta":{"timestamp":"2024-01-15T10:30:00Z","path":"/api/v1/governments/us/states/xx/legislature/lower/current"}}},"notFound":{"summary":"Resource Not Found","value":{"error":{"code":"NOT_FOUND","message":"No members found for the specified criteria","details":{"searchCriteria":{"state":"ca","chamber":"lower","active":true}}},"meta":{"timestamp":"2024-01-15T10:30:00Z","path":"/api/v1/governments/us/states/ca/legislature/lower/current"}}},"internalError":{"summary":"Internal Server Error","value":{"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred while processing the request","details":{"requestId":"req_123456789abcdef"}},"meta":{"timestamp":"2024-01-15T10:30:00Z","path":"/api/v1/members"}}},"govRoles":{"summary":"Government Roles List","value":{"data":[{"id":"us-federal-house-member","name":"U.S. House Representative","level":"federal","chamber":"lower","description":"Members of the U.S. House of Representatives serve two-year terms representing the people of a specific congressional district.","active":true,"government":{"country":"us","level":"federal","branch":"legislative"}},{"id":"us-federal-senate-member","name":"U.S. Senator","level":"federal","chamber":"upper","description":"U.S. Senators serve six-year terms representing their entire state.","active":true,"government":{"country":"us","level":"federal","branch":"legislative"}}],"pagination":{"page":1,"limit":50,"total":250,"hasMore":true},"meta":{"lastUpdated":"2024-01-15T10:30:00Z","filters":{"level":"federal","active":true}}}},"roleCountStat":{"summary":"Role Count Statistic","value":{"data":{"type":"role_count","queryId":"us-federal-house-member","jurisdiction":"us","count":435,"lastUpdated":"2024-01-15T10:30:00Z"},"meta":{"lastUpdated":"2024-01-15T10:30:00Z"}}}},"parameters":{"StateCodePath":{"name":"state","in":"path","required":true,"description":"Two-letter state code (lowercase)","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ca"}},"StateQuery":{"name":"state","in":"query","required":false,"description":"Filter by state code (two-letter lowercase)","schema":{"type":"string","pattern":"^[a-z]{2}$","example":"ca"}},"MemberIdPath":{"name":"id","in":"path","required":true,"description":"The member’s `ocdPersonId`, or the internal record id. Prefer `ocdPersonId` — it is the stable identifier across refreshes.","schema":{"type":"string","example":"ocd-person/00000000-0000-0000-0000-000000000000"}},"DistrictQuery":{"name":"district","in":"query","required":false,"description":"Filter by district identifier. Leading zeros are ignored, so `3` and `03` select the same seat. Combine with `state` and `chamber` to identify a single seat.","schema":{"type":"string","example":"30"}},"CountryQuery":{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code. DEFAULTS TO \"us\" when omitted, so existing integrations are unaffected by international data. Pass \"*\" for every country.","schema":{"type":"string","default":"us","example":"fr"}},"RoleQuery":{"name":"role","in":"query","required":false,"description":"Filter by government role ID","schema":{"type":"string","example":"us-federal-house-member"}},"PartyQuery":{"name":"party","in":"query","required":false,"description":"Filter by political party (case-insensitive partial match)","schema":{"type":"string","example":"Democratic"}},"ChamberQuery":{"name":"chamber","in":"query","required":false,"description":"Filter by legislative chamber","schema":{"type":"string","enum":["upper","lower","unicameral"]}},"LevelQuery":{"name":"level","in":"query","required":false,"description":"Filter by government level. Use with `branch` to pull a slice such as all federal executive officials.","schema":{"type":"string","enum":["federal","state","local"]}},"BranchQuery":{"name":"branch","in":"query","required":false,"description":"Filter by branch of government (legislative, executive, judicial).","schema":{"type":"string","enum":["legislative","executive","judicial"]}},"SearchQuery":{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match on the member name.","schema":{"type":"string","example":"graham"}},"ActiveQuery":{"name":"active","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean","default":true}},"SortQuery":{"name":"sort","in":"query","required":false,"description":"Sort field","schema":{"type":"string","enum":["name","state","party"],"default":"name"}},"OrderQuery":{"name":"order","in":"query","required":false,"description":"Sort order","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},"PageQuery":{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","minimum":1,"default":1}},"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"responses":{"MemberList":{"description":"List of government members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiListResponse"},"examples":{"houseMembers":{"$ref":"#/components/examples/houseMembers"}}}}},"SingleMember":{"description":"Single government member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"examples":{"houseRepresentative":{"$ref":"#/components/examples/houseRepresentative"},"senator":{"$ref":"#/components/examples/senator"},"stateRepresentative":{"$ref":"#/components/examples/stateRepresentative"},"governor":{"$ref":"#/components/examples/governor"}}}}},"BadRequest":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"invalidParameter":{"$ref":"#/components/examples/invalidParameter"}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"notFound":{"$ref":"#/components/examples/notFound"}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"internalError":{"$ref":"#/components/examples/internalError"}}}}}}}}