Meetings

The meetings, meeting repositories and minutes in a municipality

Here's how to manage meetings

The Meeting object

// Meeting
{
    "id": "me_dd3b6aa3",
    "person_id": 40, // Author of the meeting
    "title": "Special Board Meeting",
    "description": "The meeting where budgets are decided and voted on",
    "notes": "The meeting went well",
    "status": "public", // enum: draft | public | archived
    "categories": [3, 15, 29],
    "department_id": 4,
    "starts_at": "2023-02-18T01:50:00.000Z", // Meeting DateTime in UTC
    "metadata": {}, // object that can hold extra data for meetings
    "created_at": "2023-04-20T06:52:10.000Z",
    "updated_at": "2023-04-21T09:34:03.000Z",

    // agenda data
    "agenda_status": "draft", // enum: draft | in_review | public | amended
    "agenda_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/2022-04-19-forestville-annual-town-meeting-agenda.pdf", // public url of agenda file
    "agenda_text": "MORGAN\nCITY COUNCIL\nAGENDA\nJANUARY\n24\n, 2023\n–\n6\n:\n00\nP...", // text extracted from agenda file

    // minutes data
    "minutes_status": "done", // Minutes generated by HeyGov: not-started, generating, done, manual-upload

    // additional files
    "agenda_pack_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/pack.pdf", // agenda pack file url
    "meeting_minutes_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/uploaded-minutes.pdf", // meeting minutes file url
    "additional_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/Additional Doc.docx", // url of uploaded file

    // Meeting media
    "audio_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/april-19-2022-forestville-wisconsin-town-board-meeting-video-recording.mp3", 
    "audio_public_url": "https://soundcloud.com/the-meeting",
    "video_file_url": "heyville.org/meetings/me_dd3b6aa3/april-19-2022-forestville-wisconsin-town-board-meeting-video-recording.mp4",
    "video_public_url": "https://www.youtube.com/watch?v=2PvkBKUBBj8"
}

Endpoints

List meetings in a municipality

GET https://api.heygov.com/{jurisdiction_id}/meetings

Path Parameters

Name	Type	Description
jurisdiction_id*	String	The ID for the municipality

Query Parameters

Name	Type	Description
date_start_local	String	Return meetings from this date (inclusive) onward. Format = YYYY-MM-DD
date_end_local	String	Return meetings until this date (inclusive). Format = YYYY-MM-DD
limit	Number	A limit on the number of meetings to be returned. Limit can range between 1 and 100, and the default is 10.
page	Number	Which page of meetings to return. Default is 1
expand	String	Expand entities to full object results. Entities that can be expanded for meetings: department, agenda_items, categories
status	String	Filter meetings by status. Options: draft, public, archived, deleted
order_by	String	Order meetings by: title, status, starts_at, created_at, updated_at. Default: starts_at
order	String	Sort order for the order_by field. asc or desc (default)
q	String	Search query for meeting title

200: OK List of meetings

Create a meeting

POST https://api.heygov.com/{jurisdiction_id}/meetings

Path Parameters

Name	Type	Description
jurisdiction_id*	String	The unique ID for the jurisdiction

Request Body

Name	Type	Description
title*	String	Title of the meeting
description	String	Meeting description
starts_at_local*	Datetime	Meeting date & time, in jurisdiction timezone
department_id	Number	ID of the department owning this meeting

201: Created Meeting is created & object with ID is returned

400: Bad Request Meeting fields are missing or invalid

Create a meeting from an agenda file

POST https://api.heygov.com/{jurisdiction_id}/meetings/create-from-agenda

This endpoint extracts the meeting details (title, date, description, agenda items, etc) from the uploaded file

Path Parameters

Name	Type	Description
jurisdiction_id*	String	ID of the town/city/village

Request Body

Name	Type	Description
file*	File	Meeting Agenda file in PDF or text format

201: Created Meeting is created & object with ID is returned

Retrieve a meeting

GET https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}

Get full details for a meeting

Path Parameters

Name	Type	Description
jurisdiction_id*	String	ID of the HeyGov account
meeting_id*	String	ID of the meeting, starting with me_

Query Parameters

Name	Type	Description
expand	String	Expand entities to full object results. Entities that can be expanded for meetings: department, agenda_items, categories

200: OK Return meeting object

404: Not Found Meeting with specified ID not found

Edit meeting details

PUT https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}

Modify meeting fields

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String	ID of the meeting, starting with me_

200: OK

Delete meeting

DELETE https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}

Fully and irreversibly delete a meeting, meeting files, agenda items and minutes

Path Parameters

Name	Type	Description
jurisdiction_id*	String	ID for needed jurisdiction
meeting_id	String	ID of the meeting, starting with me_

200: OK Meeting and linked data are deleted

Files endpoints

Use these endpoints to upload different files needed for a meeting

Upload meeting agenda file for a meeting

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-agenda-file

Upload an existing agenda for a meeting. Agenda items will be extracted and created automatically

Path Parameters

Name	Type	Description
jurisdiction_id*	String	Town/City ID
meeting_id*	String	ID of the meeting, starting with me_

Query Parameters

Name	Type	Description
await_processing	Boolean	0 or 1 to await agenda processing or not. Default: 0

Request Body

Name	Type	Description
file*	File	Agenda file in PDF or txt format

Upload the agenda pack

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-agenda-pack-file

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String

Request Body

Name	Type	Description
file*	File	The agenda pack file

200: OK File uploaded successfully

Public url will be included in response

Upload the minutes document

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-meeting-minutes-file

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String

Request Body

Name	Type	Description
file*	File

Upload an additional file for the meeting

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-additional-file

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String

Request Body

Name	Type	Description
file*	File

Create a file upload request

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/file-upload-link

Use this endpoint to create a file upload request, that can be used in front-end to upload a large file directly to the cloud storage (bypassing the HeyGov server)

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String	ID of the meeting, starting with me_

Request Body

Name	Type	Description
filename*	String	The name of the file that will be uploaded

200: OK Returns the upload link

Agenda items endpoints

List of agenda items for a meeting

GET https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String

200: OK List of agenda items

Edit an agenda item

PUT https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items/{id}

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String
id*	String	ID of the agenda item

200: OK

Delete an agenda item

DELETE https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items/{id}

Generate minutes for a meeting

POST https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/generate-minutes

Based on the agenda items & audio/video transcript, generate full meeting minutes

Path Parameters

Name	Type	Description
jurisdiction_id*	String
meeting_id*	String

Query Parameters

Name	Type	Description
model	String	OpenAI model to use. Default is gpt-4
temperature	String	OpenAI model temperature to use. Default is 1

200: OK