Upcoming Meetings

Retrieve a paginated list of your organization’s upcoming meetings, sorted by start time. Each record includes scheduling details, capacity, the platform the meeting runs on, and the group leader (facilitator) profile.

Use this endpoint to power an “Upcoming sessions” page on your website, a calendar widget, or any internal tool that needs a forward-looking view of your organization’s scheduled meetings.

Endpoint

GET: /api/v2/organizations/:organization_id/upcoming_meetings

Authentication

Authorization: Bearer <token> header
Token must resolve to the target organization via AuthorizeApiRequest

Optional Query Parameters

Name	Type	Default	Description
`meeting_series_id`	Integer	—	When provided, returns only upcoming meetings that belong to that recurring series. Unknown ids return an empty list.
`page`	Integer	`1`	Page number (1-indexed).
`items`	Integer	`20`	Items per page. Clamped to `1..100`.

Example Request


GET /api/v2/organizations/5/upcoming_meetings?meeting_series_id=412&page=1&items=20
Authorization: Bearer <token>
Accept: application/json


curl -X GET "https://heypeers.com/api/v2/organizations/{ORG_ID}/upcoming_meetings?meeting_series_id=412&page=1&items=20" \
     -H "Authorization: Bearer {TOKEN}" \
     -H "Accept: application/json"

Success Response

200 OK


{
  "current_page": 1,
  "items": 20,
  "total_items": 8,
  "total_pages": 1,
  "meetings": [
    {
      "id": 9123,
      "name": "Morning Grief Support Circle",
      "start_time": "2026-05-23T15:00:00.000Z",
      "end_time": "2026-05-23T16:00:00.000Z",
      "duration": "1 hour",
      "duration_in_minutes": 60,
      "topic": "Grief & Loss",
      "description": "A supportive space to share and process grief.",
      "location": "heypeers",
      "meeting_series_id": 412,
      "max_attendees": 12,
      "registered_attendees": 7,
      "group_leader": {
        "id": 4501,
        "name": "Jane D.",
        "avatar": "https://heypeers-assets.s3.amazonaws.com/users/avatars/thumb/4501.png"
      }
    },
    {
      "id": 9124,
      "name": "Evening Recovery Check-in",
      "start_time": "2026-05-24T23:30:00.000Z",
      "end_time": "2026-05-25T00:30:00.000Z",
      "duration": "1 hour",
      "duration_in_minutes": 60,
      "topic": "Substance Use Recovery",
      "description": null,
      "location": "zoom",
      "meeting_series_id": null,
      "max_attendees": 20,
      "registered_attendees": 0,
      "group_leader": {
        "id": 4502,
        "name": "Sam L.",
        "avatar": "https://ssl.gstatic.com/accounts/ui/avatar_2x.png"
      }
    }
  ]
}

Response Fields

Top-level

Field	Type	Description
`current_page`	Integer	Current page number.
`items`	Integer	Page size used for the response.
`total_items`	Integer	Total number of upcoming meetings across all pages.
`total_pages`	Integer	Total number of pages.
`meetings`	Array	Meeting records on the current page, ordered by `start_time` ascending.

Meeting object

Field	Type	Description
`id`	Integer	Unique meeting identifier.
`name`	String	Meeting title.
`start_time`	String	Start time in ISO 8601 (UTC).
`end_time`	String	End time in ISO 8601 (UTC).
`duration`	String	Human-readable duration (e.g. `"1 hour"`, `"30 minutes"`).
`duration_in_minutes`	Integer	Duration in whole minutes.
`topic`	String	Meeting topic / subject.
`description`	String \| null	Longer meeting description.
`location`	String	Platform the meeting runs on: `"heypeers"` or `"zoom"`.
`meeting_series_id`	Integer \| null	Identifier shared by meetings in the same recurring series. `null` for one-off meetings.
`max_attendees`	Integer	Maximum number of attendees allowed.
`registered_attendees`	Integer	Number of registered attendees, excluding group leaders.
`group_leader`	Object	The meeting’s facilitator (see below).

`group_leader` object

Field	Type	Description
`id`	Integer	The group leader’s HeyPeers user id.
`name`	String	Display name (first name + last initial, e.g. `"Jane D."`).
`avatar`	String	URL to the leader’s thumbnail avatar. Falls back to a default avatar if unset.

Error Responses

401 Unauthorized
- { "error": "Unauthorized Access" } when the bearer token does not resolve to an organization.
- { "error": "Not Authorized" } when the token resolves to a different organization than the one in the URL.
422 Unprocessable Entity
- { "error": "Parameter meeting_series_id must be a positive integer" } when meeting_series_id is provided but is not a positive integer.

Notes

Only meetings that have not yet ended (end_time in the future) and are not canceled or completed are returned.
Results are ordered by start_time ascending (soonest first).
Pass meeting_series_id to narrow the list to a single recurring series (the same value returned in each meeting’s meeting_series_id field). The filter is always scoped to your organization, so an id that does not belong to one of your series returns an empty list.
Responses are paginated. The defaults are items=20 and page=1.
For organizations running an Employee Assistance Program (EAP), the list also includes the organization’s associated HeyPeers Counseling (HPC) meetings.
To list the upcoming meetings for a single member rather than the whole organization, use the Member’s Upcoming Meetings endpoint.