# People

> Elected officials, their council appointments, departments and job postings.

The people a government's own pages name in office, and its public offices. Staff are never listed by name: a department's contact is an office's line, never a person's.

## Elected officials

### `GET /v1/officials`

**List elected officials.** Mayors, councillors, chairs and directors as the government's own page names them. Billed as one records request a page. Filters: jurisdiction, region, country, kind, since.

[Reference and playground for list elected officials](https://data.heytownhall.com/docs/reference/people-in-office/get-v1-officials)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | The office: mayor, councillor, chair, director.                          |
| `since`        | Records read at or after this instant: what is new since your last read. |

Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)).

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `country`         | string or null |                                                                 |
| `region`          | string or null |                                                                 |
| `office`          | string         |                                                                 |
| `name`            | string         |                                                                 |
| `title`           | string or null |                                                                 |
| `takes_office`    | string or null | Set for someone elected and not yet sworn in.                   |
| `source_url`      | string or null | The page, document, video or platform the record was read from. |
| `read_at`         | string or null | When it was read.                                               |

## Council appointments

### `GET /v1/council-appointments`

**List council appointments.** The boards and committees each elected official sits on, from the newest annual report. Billed as one records request a page. Filters: jurisdiction.

[Reference and playground for list council appointments](https://data.heytownhall.com/docs/reference/people-in-office/get-v1-council-appointments)

| Parameter      | What it takes      |
| -------------- | ------------------ |
| `jurisdiction` | A jurisdiction id. |

Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)).

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `fiscal_year`     | number or null |                                                                 |
| `member_name`     | string or null |                                                                 |
| `appointed_to`    | string or null |                                                                 |
| `role`            | string or null |                                                                 |
| `source_url`      | string or null | The page, document, video or platform the record was read from. |
| `read_at`         | string or null | When it was read.                                               |

## Departments

### `GET /v1/departments`

**List departments.** Departments and their published public contacts (an office's line, never a person's). Billed as one records request a page. Filters: jurisdiction, region, country, kind, since.

[Reference and playground for list departments](https://data.heytownhall.com/docs/reference/people-in-office/get-v1-departments)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | The department's role, such as planning.                                 |
| `since`        | Records read at or after this instant: what is new since your last read. |

Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)).

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `country`         | string or null |                                                                 |
| `region`          | string or null |                                                                 |
| `department`      | string or null |                                                                 |
| `role`            | string or null |                                                                 |
| `phone`           | string or null |                                                                 |
| `email`           | string or null |                                                                 |
| `hours`           | string or null |                                                                 |
| `source_url`      | string or null | The page, document, video or platform the record was read from. |
| `read_at`         | string or null | When it was read.                                               |

## Job postings

### `GET /v1/jobs`

**List job postings.** Open job postings with pay, hours and terms as the posting prints them. Billed as one records request a page. Filters: jurisdiction, region, country, kind, since.

[Reference and playground for list job postings](https://data.heytownhall.com/docs/reference/posts/get-v1-jobs)

| Parameter      | What it takes                                                            |
| -------------- | ------------------------------------------------------------------------ |
| `jurisdiction` | A jurisdiction id.                                                       |
| `region`       | A two-letter province or state code.                                     |
| `country`      | CA or US.                                                                |
| `kind`         | The employment type, such as full_time.                                  |
| `since`        | Records read at or after this instant: what is new since your last read. |

Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)).

| Field             | Type           | What it holds                                                   |
| ----------------- | -------------- | --------------------------------------------------------------- |
| `id`              | string         |                                                                 |
| `jurisdiction_id` | string         |                                                                 |
| `country`         | string or null |                                                                 |
| `region`          | string or null |                                                                 |
| `title`           | string         |                                                                 |
| `summary`         | string or null |                                                                 |
| `location`        | string or null |                                                                 |
| `published_at`    | string or null | ISO 8601 instant, UTC.                                          |
| `closes_at`       | string or null | ISO 8601 instant, UTC.                                          |
| `status`          | string or null |                                                                 |
| `employment_type` | string or null |                                                                 |
| `union_status`    | string or null |                                                                 |
| `work_kind`       | string or null |                                                                 |
| `pay`             | string or null | As printed.                                                     |
| `hours`           | string or null |                                                                 |
| `work_location`   | string or null |                                                                 |
| `page_read`       | boolean        |                                                                 |
| `source_url`      | string or null | The page, document, video or platform the record was read from. |
| `read_at`         | string or null | When it was read.                                               |

### `GET /v1/jobs/{id}`

**Retrieve a job.** One job posting with its headed sections. Billed as one records request.

[Reference and playground for retrieve a job](https://data.heytownhall.com/docs/reference/posts/get-v1-jobs-id)

Path: `{id}` such as 123456.

| Field      | Type            | What it holds |
| ---------- | --------------- | ------------- |
| `sections` | array of object |               |