{
  "openapi": "3.0.0",
  "info": {
    "title": "FiscalNote Organizations API - Version 1.0",
    "description": "Search for US Committees and US and Global Organizations.\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/organizations/v1/](https://data.fiscalnote.com/organizations/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/organizations/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/search": {
      "post": {
        "tags": [
          "Organizations"
        ],
        "summary": "Search for Organizations",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/orgs_search_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/orgs_search_response"
                }
              }
            }
          },
          "206": {
            "description": "Partial Content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/orgs_search_response"
                }
              }
            }
          }
        }
      }
    },
    "/fetch": {
      "post": {
        "tags": [
          "Organizations"
        ],
        "summary": "Search by organization ID(s)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/orgs_by_id_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/orgs_by_id_response"
                }
              }
            }
          },
          "206": {
            "description": "Partial Content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/orgs_by_id_response"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "schemas": {
      "orgs_search_request": {
        "title": "Organizations Search - Request",
        "type": "object",
        "properties": {
          "name": {
            "description": "Filter on organization name",
            "type": "string",
            "example": "Congressional Bagel Caucus"
          },
          "type": {
            "description": "Filter on organization type. `committee` refers to US state and federal committees, while `generic_organization` refers to all other organization types, including executive branch departments, legislative districts, congressional seats, etc.",
            "type": "string",
            "enum": [
              "committee",
              "generic_organization"
            ]
          },
          "locality_code": {
            "description": "Filter on organization locality_code. Can be an array of one or more localities. To get all US states, use `US-*` to expand the list.",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "US",
              "US-*",
              "EU"
            ]
          },
          "exclude_locality": {
            "description": "A single or comma-separated list of localities to *exclude* from your response.\nIf used alone, data from all remaining localities will be returned.  If used with `locality_code`, only data from localities in `locality_code` *not* in `exclude_locality` will be returned. \nTo specify all 50 US States, plus DC, use \"US-\\*\".\n",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "CA-*",
              "US-CA",
              "US-OR",
              "EU"
            ]
          },
          "include_members": {
            "description": "*COMMITTEES ONLY* A boolean to include available committee member information or not. Member information not available for `generic_organizations`.",
            "type": "boolean",
            "default": false
          },
          "is_active": {
            "description": "*COMMITTEES ONLY* Filter based on if committees are currently active or not.\n\n Active information not available for generic_organizations; this filter has no affect on generic_organization types,\n and all generic_organizations that meet the other criteria will be returned.\n\n If True, only active committees will be returned.\n If False, only inactive committees will be returned. \n Defaults to True. ",
            "type": "boolean",
            "default": true
          },
          "continuation_token": {
            "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).",
            "type": "string",
            "example": "QlpoOTFBWSZTWaavcyAADvHfgAwAUAd%2F"
          },
          "limit": {
            "description": "Results limit, or page size, for this request. Maximum number of entities that will be returned in one response. The underlying implementation uses a default value of 10 if no limit is specified.\nIf the maximum limit of 500s is exceeded, the response will automatically truncate to the maximum limit and return a 206 Partial Content response.",
            "maximum": 500,
            "minimum": 0,
            "type": "integer",
            "default": 10,
            "example": 10
          }
        }
      },
      "orgs_search_response": {
        "title": "Organizations Search - Response",
        "required": [
          "results"
        ],
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/organization"
            },
            "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
          }
        }
      },
      "orgs_by_id_request": {
        "title": "Organizations by ID - Request",
        "description": "Format to fetch organizations by ID",
        "type": "object",
        "required": [
          "ids"
        ],
        "properties": {
          "ids": {
            "description": "An array of organization IDs.  Maximum 100. If the maximum limit is exceeded, the response will automatically truncate to the first 100 IDs and return a 206 Partial Content response.",
            "type": "array",
            "items": {
              "type": "string",
              "example": [
                "AjVR8i9A",
                "ABVrZfkA"
              ]
            }
          },
          "include_members": {
            "description": "*COMMITTEES ONLY* A boolean to include committee member information or not. Member information not available for `generic_organizations`.",
            "type": "boolean",
            "default": false
          },
          "custom_authentication_token": {
            "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 Organization API. Custom data includes your uploaded/custom contact organization 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."
          }
        }
      },
      "orgs_by_id_response": {
        "title": "Organizations by ID - Response",
        "type": "array",
        "description": "An array of organization objects.",
        "items": {
          "$ref": "#/components/schemas/organization"
        }
      },
      "organization": {
        "title": "Organization",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "A hashed, unique ID.",
            "example": "PAo79fEA"
          },
          "entity_id": {
            "type": "string",
            "description": "An unhashed ID, comprised of the entity type and a numeric entity ID.",
            "example": "committee-8647"
          },
          "type": {
            "title": "Organization Type",
            "description": "Whether the organization is a US state or federal `committee`, or a `generic_organization`  (e.g., executive branch department, state agency, legislative chamber, legislative district, international committee, etc.),\n or `contact_organization` (your organization's uploaded contact data on the FN website).",
            "type": "string",
            "example": "committee",
            "enum": [
              "generic_organization",
              "committee",
              "contact_organization"
            ]
          },
          "subtype": {
            "title": "Specific Organization Type",
            "description": "The subtype of the organization.\n* If `type = committee`, subtypes include: \n  - `committee`\n  - `caucus`\n  - `subcommittee`\n* If `type = generic organization`, subtypes include:\n  - `generic_organization`\n  - `government`\n  - `legislative`\n  - `judicial`\n  - `executive`\n  - `legislative_district`\n  - `legislative_chamber`\n  - `political_party`\n  - international `committee`\n  - potential additional values\n* If `type = contact_organization`, `None`.",
            "type": "string",
            "example": "caucus"
          },
          "locality_code": {
            "title": "Organization 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'.",
            "example": "US-IL"
          },
          "name": {
            "title": "Organization Name",
            "type": "string",
            "description": "The name of the organization.",
            "example": "Department of Healthcare and Family Services"
          },
          "chamber": {
            "title": "Organization Chamber",
            "type": "string",
            "description": "For committees, the legislative chamber the committee belongs to.",
            "example": "UPPER"
          },
          "description": {
            "title": "Description",
            "type": "string",
            "description": "A summary of the organization.",
            "example": "The Subcommittee on Commodities, Risk Management, and Trade oversees matters regarding production agriculture, including commodity programs, crop insurance, commodity exchanges, agriculture trade, international food assistance, and credit."
          },
          "contacts": {
            "$ref": "#/components/schemas/contacts"
          },
          "parent": {
            "title": "Parent Organization",
            "description": "The parent organization of this organization, if one exists.",
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "description": "The hashed, unique ID of the parent organization.",
                "example": "PAo79fEA"
              },
              "entity_id": {
                "type": "string",
                "description": "The unhashed ID of the parent organization, comprised of the entity type and a numeric entity ID.",
                "example": "committee-8647"
              },
              "name": {
                "type": "string",
                "description": "The name of the parent organization.",
                "example": "State Department of Health"
              }
            }
          },
          "is_active": {
            "title": "Active Committee",
            "type": "boolean",
            "description": "A boolean field, `True` of the committee is currently active, `False` otherwise. Only available for committee type organizations."
          },
          "members": {
            "title": "Committee Members",
            "description": "A list of the legislators assigned to a committee. Generally only available for active committees. To get members of generic organizations, use the People API and filter by `role_related_org_id`.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/member"
            }
          }
        }
      },
      "contacts": {
        "type": "object",
        "title": "Contact Information",
        "description": "The available contact information for the organization, including addresses, websites, emails, and phones.",
        "additionalProperties": false,
        "properties": {
          "phones": {
            "type": "array",
            "title": "Phone Numbers",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string",
                  "example": "1"
                },
                "number": {
                  "type": "string",
                  "example": "304-258-5133"
                },
                "extension": {
                  "type": "string",
                  "example": "435"
                },
                "type": {
                  "enum": [
                    "PHONE",
                    "FAX",
                    "TTY",
                    "SMS"
                  ],
                  "type": "string",
                  "example": "PHONE"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "title": "Addresses",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "subdivision": {
                  "type": "string",
                  "example": "ca"
                },
                "city": {
                  "type": "string",
                  "example": "Sacramento"
                },
                "zip_code": {
                  "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"
                },
                "address_type": {
                  "enum": [
                    "CAMPAIGN",
                    "CAPITOL",
                    "DISTRICT",
                    "EXECUTIVE",
                    "HOME",
                    "STAFF"
                  ],
                  "type": "string",
                  "example": "EXECUTIVE"
                },
                "phones": {
                  "type": "array",
                  "items": {
                    "title": "Phone Numbers",
                    "type": "object",
                    "properties": {
                      "country_code": {
                        "type": "string",
                        "example": "1"
                      },
                      "number": {
                        "type": "string",
                        "example": "304-258-5133"
                      },
                      "extension": {
                        "type": "string",
                        "example": "435"
                      },
                      "type": {
                        "enum": [
                          "PHONE",
                          "FAX",
                          "TTY",
                          "SMS"
                        ],
                        "type": "string",
                        "example": "PHONE"
                      }
                    }
                  }
                },
                "is_mailing": {
                  "type": "boolean",
                  "example": true
                },
                "country": {
                  "type": "string",
                  "example": "USA"
                },
                "unparsed_address": {
                  "description": "If an address cannot be split up into its parts, the full address will be returned here.",
                  "type": "string"
                }
              }
            }
          },
          "websites": {
            "type": "array",
            "title": "Websites",
            "items": {
              "type": "string"
            },
            "example": [
              "http://www.prc.gov/contact",
              "http://www.prc.gov/"
            ]
          },
          "emails": {
            "type": "array",
            "title": "Emails",
            "items": {
              "type": "string"
            },
            "example": [
              "PRC-OAC@prc.gov"
            ]
          }
        }
      },
      "member": {
        "title": "Committee Member",
        "description": "A legislator belonging to the organization.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The hashed, unique ID for the legislator.",
            "example": "AkdJJI86"
          },
          "entity_id": {
            "type": "string",
            "description": "An unhashed ID, comprised of the entity type and a numeric entity ID.",
            "example": "legislator-7572"
          },
          "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"
              }
            }
          },
          "photo_url": {
            "type": "string",
            "example": "https://s3.amazonaws.com/fn-document-service-dev/file-by-sha384/16488f47fd61ea4f279e1a9670cf13972408d1cf8746d2d1a0166041c93d60913c2a6e66095df111db2573dda214ebab"
          },
          "title": {
            "type": "string",
            "description": "The legislator's title on the committee.",
            "example": "chair"
          },
          "party": {
            "type": "string",
            "example": "democrat",
            "description": "The political party this legislator belongs to."
          },
          "district": {
            "type": "string",
            "example": "Rhode Island US Senate",
            "description": "The legislative district this legislator represents."
          },
          "chamber": {
            "type": "string",
            "example": "upper",
            "description": "The legislative chamber this legislator belongs to."
          }
        }
      }
    }
  }
}