{
  "openapi": "3.0.0",
  "info": {
    "title": "FiscalNote People API v1",
    "description": "Search for people who influence and create global policy.\n\nIf you are interested in access to FiscalNote's APIs, please reach out via [https://fiscalnote.com/demo](https://fiscalnote.com/demo).\n\n**Technical Notes**:\n\n*Base URL*: [https://data.fiscalnote.com/people/v1/](https://data.fiscalnote.com/people/v1/)\n\n*Rate Limiting*: Rate limiting rules are enabled for all API routes. By default: 60 requests per 60 seconds.\n\n*Quota*: Quotas are enabled for all API routes. By default: 500 requests per 24 hours. \n\n*Authorization Instructions*:\n\nRequest an API key via [https://apidocs.fiscalnote.com/apis/](https://apidocs.fiscalnote.com/apis/) after creating a Developer account or logging in.\nWhen your request is approved, follow the link that will be emailed to you, and save the generated username and password.\n\nKeep these private. Use Basic Authorization in all your request headers. \n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://data.fiscalnote.com/people/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "tags": [
          "Stakeholders"
        ],
        "summary": "Search for people",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Filter on name",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "Kamala Harris"
            }
          },
          {
            "name": "stakeholder_type",
            "in": "query",
            "description": "Filter on stakeholder type - a more granular version of `role_type`. \"Local Officials\" includes any city- or county-level official, currently available in the US only. All other types are at a state/province, national, or international level.\nIt is recommended to use this filter instead of `role_type`.",
            "schema": {
              "type": "string",
              "example": "Senators",
              "enum": [
                "All Legislators",
                "Council of the EU",
                "Members of the EU Parliament",
                "Representatives",
                "Senators",
                "All Government Executives",
                "Attorneys General",
                "Comptrollers",
                "Directors",
                "EU Commission",
                "Governors",
                "Lt. Governors",
                "Secretaries",
                "Treasurers",
                "Local Officials"
              ]
            }
          },
          {
            "name": "role_type",
            "in": "query",
            "description": "Filter on role type",
            "style": "form",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/role_type"
            }
          },
          {
            "name": "role_title",
            "in": "query",
            "description": "Filter on role title",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "Vice President"
            }
          },
          {
            "name": "role_related_org_name",
            "in": "query",
            "description": "Filter on role related organization name",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "Office of the Vice President"
            }
          },
          {
            "name": "role_related_org_id",
            "in": "query",
            "description": "Filter on a role related organization id",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "6qkqMU2D"
            }
          },
          {
            "name": "role_related_seat_id",
            "in": "query",
            "description": "Filter on role related seat id",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "80M4oSRL"
            }
          },
          {
            "name": "role_locality_code",
            "in": "query",
            "description": "Filter on role_locality_code",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string",
              "example": "US"
            }
          },
          {
            "name": "include_staffers",
            "in": "query",
            "description": "Filter based on the include_staffers",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "continuation_token",
            "in": "query",
            "description": "Continuation token for paging. When this parameter is null/not present, the first page of results will be returned. To retrieve additional pages, this value is returned in the response payload for each page, and can then be passed in this parameter on the next call to retrieve the next page. If the continuation_token returned in the response is null, there are no further pages to get (you have reached the end of the results).",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results limit, or page size, for this request. Maximum number of entities that will be returned. The underlying implementation may already use a default value, typically 10, if none is specified. If the maximum limit is exceeded, the response will automatically truncate to the maximum number of results and return a 206 Partial Content response.",
            "style": "form",
            "explode": true,
            "schema": {
              "maximum": 500,
              "minimum": 0,
              "type": "integer",
              "default": 10,
              "example": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/people_search_response"
                }
              }
            }
          },
          "206": {
            "description": "Partial Content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/people_search_response"
                }
              }
            }
          }
        }
      }
    },
    "/{id}": {
      "get": {
        "tags": [
          "Stakeholders"
        ],
        "summary": "Search by a single person by ID",
        "parameters": [
          {
            "name": "include_staffers",
            "in": "query",
            "description": "If true, also return information for the staffers related to each person's role as a government official.",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "custom_authentication_token",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "ihfi7wy8r72bdojwha9d8w"
            },
            "description": "An additional authentication token (the same as used in all `AppData` API requests), required if you want to get any custom data from the People API. Custom data includes your uploaded/custom contact data that exists on the FiscalNote Application. If you request any custom contact IDs and do not pass in your `custom_authentication_token`, you will receive a `401 Unauthorized` error.\nYou can receive your `custom_authentication_token` by reaching out to the FiscalNote API Team.\n* Only * required if custom contact IDs are requested."
          },
          {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "style": "simple",
            "schema": {
              "type": "string",
              "example": "AjVR8i9A"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/person"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "schemas": {
      "people_search_response": {
        "title": "People Search Response Body",
        "required": [
          "results"
        ],
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/person"
            },
            "description": "The records returned on this page"
          },
          "continuation_token": {
            "type": "string",
            "description": "A continuation token that can be used to get the next page of results. If absent, there is no next page.",
            "example": "AhXqeJPsBEABci30hEoHXdQU9QE"
          },
          "estimated_total_results": {
            "type": "integer",
            "description": "Estimated total result count over all pages for this query. It will be returned by the server if available, but is not guaranteed.",
            "example": 1123
          }
        }
      },
      "person": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "example": "PAo79fEA",
            "description": "A hashed, unique ID."
          },
          "entity_id": {
            "type": "string",
            "example": "legislator-764791",
            "description": "An unhashed ID, comprised of the entity type and a numeric entity ID."
          },
          "name": {
            "$ref": "#/components/schemas/name"
          },
          "biography": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/biography"
            },
            "description": ""
          },
          "birthday": {
            "$ref": "#/components/schemas/date"
          },
          "birthPlace": {
            "type": "string",
            "example": "Dallas, TX"
          },
          "family": {
            "type": "string",
            "example": "Dax and 4 children"
          },
          "photoUrl": {
            "type": "string",
            "example": "https://s3.amazonaws.com/fn-document-service-dev/file-by-sha384/16488f47fd61ea4f279e1a9670cf13972408d1cf8746d2d1a0166041c93d60913c2a6e66095df111db2573dda214ebab"
          },
          "gender": {
            "$ref": "#/components/schemas/gender"
          },
          "roles": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "member": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/member"
                }
              },
              "governmentOfficial": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/governmentOfficial"
                }
              }
            }
          }
        }
      },
      "date": {
        "title": "date",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "day": {
            "type": "integer",
            "example": 1
          },
          "month": {
            "type": "integer",
            "example": 12
          },
          "year": {
            "type": "integer",
            "example": 2020
          }
        }
      },
      "gender": {
        "title": "gender",
        "enum": [
          "MALE",
          "FEMALE",
          "NONBINARY"
        ],
        "type": "string",
        "example": "MALE"
      },
      "governmentOfficial": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "seat": {
            "$ref": "#/components/schemas/seat"
          },
          "organization": {
            "$ref": "#/components/schemas/organization"
          },
          "term": {
            "$ref": "#/components/schemas/term"
          },
          "district": {
            "$ref": "#/components/schemas/district"
          },
          "branch": {
            "$ref": "#/components/schemas/branch"
          },
          "locality_code": {
            "type": "string",
            "example": "US-CA"
          },
          "title": {
            "type": "string",
            "example": "Representative"
          },
          "reelectionYear": {
            "type": "integer",
            "description": "For elected seats, the year when this role is next up for reelection.",
            "example": 2022
          },
          "contacts": {
            "$ref": "#/components/schemas/contact_info"
          },
          "staffers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/staffer"
            },
            "description": "Some Government Officials also have staffers; this list describes those People who have said \"staffer\" roles."
          }
        }
      },
      "member": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "parent": {
            "$ref": "#/components/schemas/parent"
          },
          "type": {
            "$ref": "#/components/schemas/member_type"
          },
          "title": {
            "type": "string",
            "example": "State Committee Member"
          },
          "term": {
            "$ref": "#/components/schemas/term"
          },
          "contacts": {
            "$ref": "#/components/schemas/contact_info"
          }
        },
        "description": "A member"
      },
      "term": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "start": {
            "$ref": "#/components/schemas/date"
          },
          "end": {
            "$ref": "#/components/schemas/date"
          },
          "isActive": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "contact_info": {
        "title": "contact_info",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/phone_number"
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "zulma.lopez@house.ga.gov"
            ]
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/address"
            }
          },
          "websites": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "http://veterans.house.gov/women-veterans-taskforce/contact",
              "http://veterans.house.gov/women-veterans-taskforce"
            ]
          }
        }
      },
      "phone_number": {
        "title": "phone_number",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "countryCode": {
            "type": "string",
            "example": "1"
          },
          "number": {
            "type": "string",
            "example": "304-258-5133"
          },
          "extension": {
            "type": "string",
            "example": "435"
          },
          "type": {
            "$ref": "#/components/schemas/phone_type"
          }
        }
      },
      "address": {
        "title": "address",
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "subdivision": {
            "type": "string",
            "example": "ca"
          },
          "city": {
            "type": "string",
            "example": "Sacramento"
          },
          "zipCode": {
            "type": "string",
            "example": "94249-0024"
          },
          "street": {
            "type": "string",
            "example": "25 Independence Avenue"
          },
          "street2": {
            "type": "string",
            "example": "PO Box 942849"
          },
          "building": {
            "type": "string",
            "example": "California Assembly"
          },
          "room": {
            "type": "string",
            "example": "208"
          },
          "addressType": {
            "$ref": "#/components/schemas/addressType"
          },
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/phone_number"
            },
            "description": ""
          },
          "is_mailing": {
            "type": "boolean",
            "example": true
          },
          "country": {
            "type": "string",
            "example": "USA"
          },
          "unparsedAddress": {
            "type": "string"
          }
        }
      },
      "addressType": {
        "enum": [
          "CAMPAIGN",
          "CAPITOL",
          "DISTRICT",
          "EXECUTIVE",
          "HOME",
          "STAFF"
        ],
        "type": "string",
        "example": "CAMPAIGN"
      },
      "biography": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "example": "Marc Berman was first elected to the California State Assembly in November 2016 to represent the 24th District, which includes southern San Mateo County and northern Santa Clara County in the heart of Silicon Valley. In the Assembly, Marc serves as chair of the Committee on Elections and Redistricting, where he has become a leading voice on protecting voters from deceptive elections practices, making election information more accessible to voters, and improving election cybersecurity and campaign finance disclosure. In addition, Marc is one of only two members to chair two select committees. The Select Committee on the Master Plan for Higher Education in California is taking a methodical review of the 1960 Master Plan to ensure that California's higher education system works for students in the 21st century economy. The Select Committee on the Census leads the Assembly's efforts in preparing California for the 2020 Census, which is used to determine the number of seats each state has in the House of Representatives as well as distribute tens of billions of dollars to state and local governments. Marc also serves on the following Assembly Standing Committees- Governmental Organization; Insurance; Privacy and Consumer Protection; and Transportation. In his first three years in the Assembly, Marc has had one of the highest rates of success in the Legislature, authoring legislation related to a number of issues, including elections, the 2020 Census, education, youth mental health, sexual assault, firearm safety, deepfakes, housing, and the environment. Marc has sent 47 bills to the Governor in his first three years in office. Marc served on the Palo Alto City Council prior to being elected to the Assembly, where he was a leader on issues such as infrastructure improvements and financial transparency. While serving on the Palo Alto City Council, Marc worked for the Silicon Valley Education Foundation, a non-profit focused on increasing access to high quality STEM education and closing the achievement gap in Silicon Valley public schools. Prior to his work in the non-profit sector, Marc was an attorney with Latham & Watkins LLP and Merino Yebri, LLP. Marc successfully represented pro bono clients seeking protection under the Violence Against Women Act and asylum in the United States due to political persecution in the Democratic Republic of the Congo. He also served as pro bono counsel to Spark, a national youth development non-profit. Marc was born in Dallas, Texas, and raised in Palo Alto, where he graduated from Palo Alto High School. He earned a degree in Political Science from Georgetown University. While in college, Marc began his public service in Palo Alto, working in Congresswoman Anna Eshoo's District Office. He also served as a summer analyst in the Voting Section of the Civil Rights Division of the Justice Department. Marc went on to graduate from law school at the University of Southern California, where he was elected president of the Student Bar Association and served for two years on the Southern California Law Review."
          },
          "date": {
            "$ref": "#/components/schemas/date"
          },
          "source": {
            "type": "string",
            "example": "Legislative Official Bio"
          }
        }
      },
      "branch": {
        "enum": [
          "legislative",
          "executive",
          "judicial"
        ],
        "type": "string",
        "description": "The branch of government that this role belongs to.",
        "example": "legislative"
      },
      "district": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Georgia House District 086"
          },
          "code": {
            "type": "string"
          }
        },
        "description": "The region that this role represents within the “locality_code” level of government, if relevant. Primarily applies to Legislators. (Some districts may be at-large, such as US Federal Senators for their entire state.)"
      },
      "name": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "full": {
            "type": "string",
            "example": "Marc Berman"
          },
          "first": {
            "type": "string",
            "example": "Marc"
          },
          "last": {
            "type": "string",
            "example": "Berman"
          },
          "nick": {
            "type": "string",
            "example": "Marc"
          },
          "prefix": {
            "type": "string",
            "example": "Hon"
          },
          "suffix": {
            "type": "string",
            "example": "IV"
          },
          "pronunciation": {
            "type": "string",
            "example": "BUR-men"
          }
        }
      },
      "organization": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "An opaque unique identifier that may be passed as the “:id” path parameter to the /organizations/:id endpoint to get a detailed response for the parent organization entity.",
            "example": "6KEgdSrP"
          },
          "type": {
            "$ref": "#/components/schemas/org_type"
          },
          "name": {
            "type": "string",
            "description": "The full name of the parent organization entity, for convenience.",
            "example": "Georgia House District 086"
          },
          "title": {
            "type": "string",
            "example": "Representative"
          },
          "locality_code": {
            "type": "string",
            "description": "An ISO code that represents the relevant level of government for this entity. For federal governments, this will use the ISO 3166-1 alpha-2 country codes (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), e.g. 'US', 'GB'. For subdivision governments, this will use the ISO 3166-2 subdivision codes (https://en.wikipedia.org/wiki/ISO_3166-2), e.g. 'US-CA'. For the European Union, locality_code will simply be 'EU'."
          },
          "branch": {
            "$ref": "#/components/schemas/branch"
          },
          "district": {
            "$ref": "#/components/schemas/district"
          }
        },
        "description": "The Organization to which this government position is accountable."
      },
      "parent": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "An opaque unique identifier that may be passed as the “:id” path parameter for the appropriate endpoint (determined by “resourceType”) to get the detailed response for the parent entity.",
            "example": "4aGRrI46"
          },
          "resourceType": {
            "$ref": "#/components/schemas/resourceType"
          },
          "name": {
            "type": "string",
            "description": "The full name of the parent entity, for convenience.",
            "example": "Assembly Select Committee on Aerospace"
          },
          "organization_type": {
            "type": "string",
            "description": "If “resourceType” is “organization,” indicates its “type” for convenience. (See organization.type for reference).",
            "example": "committee"
          }
        },
        "description": "The Organization or Person of which this role is a “member” or “staffer”.  e.g. this Person is a member of a parent committee; or is a staffer of a parent Legislator."
      },
      "resourceType": {
        "title": "resourceType",
        "enum": [
          "organization",
          "person"
        ],
        "type": "string",
        "description": "Identifies whether the “parent” is an “organization” or “person” entity. This identifies which API endpoint can be used to receive further information about the parent (/organizations/:id or /people/:id). In most cases, “resourceType” will be “organization” - we only expect it will be “person” for a Legislator’s staffers.",
        "example": "organization"
      },
      "role_type": {
        "title": "role_type",
        "enum": [
          "legislator",
          "executive"
        ],
        "type": "string",
        "example": "legislator"
      },
      "seat": {
        "required": [
          "id"
        ],
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        }
      },
      "staffer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "$ref": "#/components/schemas/name"
          },
          "gender": {
            "$ref": "#/components/schemas/gender"
          },
          "family": {
            "type": "string",
            "example": "A husband, 2 kids"
          },
          "photoUrl": {
            "type": "string",
            "example": "https://s3.amazonaws.com/fn-document-service-dev/file-by-sha384/16488f47fd61ea4f279e1a9670cf13972408d1cf8746d2d1a0166041c93d60913c2a6e66095df111db2573dda214ebab"
          },
          "roles": {
            "type": "object",
            "properties": {
              "member": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/staffer_role"
                    },
                    {
                      "$ref": "#/components/schemas/staffer_party"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "staffer_role": {
        "type": "object",
        "properties": {
          "parent": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The Legislator ID this staffer works for."
              },
              "resourceType": {
                "type": "string",
                "example": "person"
              },
              "name": {
                "type": "string",
                "example": "Michael J. Hough",
                "description": "The Legislator this staffer works for."
              }
            }
          },
          "type": {
            "type": "string",
            "example": "staffer"
          },
          "title": {
            "type": "string",
            "example": "Chief of Staff"
          },
          "specialties": {
            "type": "array",
            "description": "Staffermroles oftentimes have a particular set of specialty areas that they cover. This list can be useful to distinguish between multiple legislative aides with the same title, for example.",
            "items": {
              "type": "string"
            },
            "example": [
              "Aerospace",
              "Technology",
              "Immigration",
              "Women's Rights",
              "Healthcare",
              "Finance"
            ]
          },
          "contacts": {
            "$ref": "#/components/schemas/contact_info"
          }
        }
      },
      "staffer_party": {
        "type": "object",
        "properties": {
          "parent": {
            "type": "object",
            "properties": {
              "organization_type": {
                "type": "string",
                "example": "political_party"
              },
              "resourceType": {
                "type": "string",
                "example": "organization"
              },
              "name": {
                "type": "string",
                "example": "Democratic Party",
                "description": "The Political Party this staffer belongs to."
              }
            }
          },
          "type": {
            "type": "string",
            "example": "member"
          },
          "title": {
            "type": "string",
            "example": "member"
          }
        }
      },
      "member_type": {
        "enum": [
          "staffer",
          "member"
        ],
        "type": "string",
        "description": "Distinguishes whether the role is that of a “member” or a “staffer” since both fall under this same “roles.member” array - particularly useful when “parent” is e.g. a committee or caucus, which may have both members and staffers with very different meanings.",
        "example": "staffer"
      },
      "phone_type": {
        "title": "phone_type",
        "enum": [
          "PHONE",
          "FAX",
          "TTY",
          "SMS"
        ],
        "type": "string",
        "example": "PHONE"
      },
      "org_type": {
        "enum": [
          "government",
          "executive",
          "legislative",
          "judicial",
          "nongovernmental",
          "political_party",
          "legislative_chamber",
          "legislative_district",
          "agency",
          "department",
          "committee",
          "caucus",
          "parliament",
          "other"
        ],
        "type": "string",
        "description": "The parent organization’s “type”.",
        "example": "legislative_district"
      }
    }
  }
}