# Find elected officials by region

This resource provides the ability to list elected officials by level and region rather than for a single geographic location. The endpoint is filtered by district type and region, and sorted by last_name, first_name.

Cost: 50 credits

Permission: Please contact the Cicero Team to request access to this resource.

Endpoint: GET /officials_by_region

## Header parameters:

  - `Accept` (string, required)
    Format of the response.
    Enum: "application/json", "*/*"

  - `Content-Type` (string, required)
    Format of the request.
    Enum: "application/json", "application/xml"

## Query parameters:

  - `format` (string)
    Specify the desired format of the response.
    Enum: "json", "xml"

  - `customer_id` (string, required)
    Required. The License Key issued by Melissa.
    Example: "{REPLACE-WITH-YOUR-LICENSE-KEY}"

  - `district_type` (string, required)
    Required. The type of district.
    Example: "NATIONAL_LOWER"

  - `country` (string, required)
    Required. The country of the location (Use ISO 3166-1 alpha-2 code) used as a filter.
    Example: "US"

  - `city` (string)
    The city of the location used as a filter.

  - `state` (string)
    The state of the location used as a filter.
    Example: "CA"

  - `district_id` (string)
    The ID, number, or name of the official's district.

  - `max` (integer)
    The maximum number of objects to return.

  - `offset` (integer)
    Number of items to skip in the response, starting from the beginning of the list.

  - `key` (string)
    The License Key issued by Melissa.

## Response 200 fields (application/json):

  - `response` (object)

  - `response.errors` (array)
    If the request encountered an error or errors, details about the error(s) will be contained in this field.

  - `response.messages` (array)
    Contains the resources matching the request query, if any.

  - `response.results` (object)
    Contains additional information about the outcome of a request that is not an error and not part of a query result.

  - `response.results.officials` (array)

  - `response.results.officials.first_name` (string)
    First name of the official. Sometimes, an official will have a preferred_name that they are more commonly known by.

  - `response.results.officials.middle_initial` (string)
    Middle name or initial of the official.

  - `response.results.officials.last_name` (string)
    Last name of the official.

  - `response.results.officials.preferred_name` (string)
    A name commonly used instead of the official's given first name. This property has a value only if it differs from the first_name.

  - `response.results.officials.salutation` (string)
    Official's formal salutation. Some assemblies use formal titles such as “Honorable”.

  - `response.results.officials.name_suffix` (string)
    Name suffix of the official (e.g., “Jr.”, “III”, “Ph.D.”).

  - `response.results.officials.sk` (number)
    The surrogate key for the official.

  - `response.results.officials.party` (string)
    Political party designation of the official. Might be “Nonpartisan” in cases where the government specifically uses that term.

  - `response.results.officials.district` (object)

  - `response.results.officials.district.district_id` (string)
    The identifying code for the district within its delegation or district type. For example, a legislative delegation's 5th district would probably have a district_id of '5'. Non-legislative districts might have an ID assigned by the managing agency (e.g., US Census Block Groups have a GEOID).

  - `response.results.officials.district.district_type__name_short` (string)
    The level of government the district represents. See the district_type metadata endpoint for a list of possibilities.

  - `response.results.officials.district.subtype` (string)
    An additional categorization within district_type.

  - `response.results.officials.district.label` (string)
    Descriptive text associated with a district_id, such as the label for the district (e.g. “5th Ward”), or a full label for the district (e.g. “Sealaska Alaska Native Regional Corporation”).

  - `response.results.officials.state` (string)
    The state, province, or region of the official's district.

  - `response.results.officials.chamber__name_formal` (string)
    The formal name of the official's chamber.

  - `response.results.officials.title` (string)
    The primary title the official holds.

  - `response.results.officials.addresses` (array)
    A list of address objects with the official's contact information, such as mailing address, phone, and fax.

  - `response.results.officials.addresses.address_1` (string)
    The first line of the street address.

  - `response.results.officials.addresses.address_2` (string)
    The second line of the street address.

  - `response.results.officials.addresses.address_3` (string)
    The third line of the street address.

  - `response.results.officials.addresses.city` (string)
    The city of the address.

  - `response.results.officials.addresses.state` (string)
    The state, province, or other region of the address.

  - `response.results.officials.addresses.postal_code` (string)
    The postal code for the address.

  - `response.results.officials.addresses.phone_1` (string)
    The primary phone number for contacting the address.

  - `response.results.officials.addresses.fax_1` (string)
    The primary fax number for the address.

  - `response.results.officials.addresses.phone_2` (string)
    The secondary phone number for contacting the address.

  - `response.results.officials.addresses.fax_2` (string)
    The secondary fax number for the address.

  - `response.results.officials.addresses.county` (string)
    Deprecated.

  - `response.results.officials.email_addresses` (array)
    A list of the official's email addresses.

  - `response.results.officials.phone_1` (string)
    The primary phone number for the official's primary address.

  - `response.results.officials.phone_2` (string)
    The secondary phone number for the official's primary address.

  - `response.results.officials.photo_origin_url` (string)
    A URL for a headshot photo of the official.

  - `response.results.officials.web_form_url` (string)
    A web form URL for contacting the official.

  - `response.results.officials.valid_from` (string)
    Date the official was inaugurated in this office. Changes with redistricting or election to a new office, but not when an incumbent starts a consecutive term.

  - `response.results.officials.valid_to` (string,null)
    Date the official's term in office expires. This date would be extended if the official wins re-election.

  - `response.results.officials.identifiers` (array)
    A list of abbreviated identifier objects containing only identifier_type and identifier_value for official Facebook and Twitter accounts.

  - `response.results.officials.identifiers.identifier_type` (string)
    The platform referred to by the identifier.

  - `response.results.officials.identifiers.identifier_value` (string)
    The identifying value for the official on this type of platform. Could be either a profile ID or a full URL.

  - `response.results.count` (object)

  - `response.results.count.from` (integer)

  - `response.results.count.to` (integer)

  - `response.results.count.total` (integer)

## Response 400 fields (application/json):

  - `response` (object)

  - `response.errors` (array)
    If the request encountered an error or errors, details about the error(s) will be contained in this field.
    Example: ["A detailed message about the error."]

  - `response.messages` (array)
    Contains the resources matching the request query, if any.

  - `response.results` (object)
    Contains additional information about the outcome of a request that is not an error and not part of a query result.