Member’s Upcoming Meetings

Retrieve a paginated list of the upcoming meetings a specific member is registered for or waitlisted for. In addition to the standard meeting details, each record includes the member’s own registration and waitlist status for that meeting.

Use this endpoint to show a signed-in member their personal upcoming schedule, for example inside an SSO-integrated portal on your own site.

Endpoint

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

The :id path segment is the member’s SSO identity-provider id (idp_id) — the identifier you supplied when the member was provisioned via SSO — not their HeyPeers user id.

Authentication

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

Optional Query Parameters

Name	Type	Default	Description
`page`	Integer	`1`	Page number (1-indexed).
`items`	Integer	`10`	Items per page. Clamped to `1..100`.

Example Request


GET /api/v2/organizations/5/members/sso-user-abc123/upcoming_meetings?page=1&items=10
Authorization: Bearer <token>
Accept: application/json


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

Success Response

200 OK


{
  "current_page": 1,
  "items": 10,
  "total_items": 2,
  "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",
      "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"
      },
      "waiting_status": null,
      "registered": true,
      "registered_at": "2026-05-20T18:42:11.000Z"
    },
    {
      "id": 9131,
      "name": "Anxiety & Stress Workshop",
      "start_time": "2026-05-26T17:00:00.000Z",
      "end_time": "2026-05-26T18:00:00.000Z",
      "duration": "1 hour",
      "duration_in_minutes": 60,
      "topic": "Anxiety",
      "description": null,
      "location": "zoom",
      "max_attendees": 8,
      "registered_attendees": 8,
      "group_leader": {
        "id": 4502,
        "name": "Sam L.",
        "avatar": "https://ssl.gstatic.com/accounts/ui/avatar_2x.png"
      },
      "waiting_status": "waiting",
      "registered": false,
      "registered_at": null
    }
  ]
}

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.

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"`.
`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).
`waiting_status`	String \| null	The member’s waitlist status for this meeting, when the meeting has a waitlist and the member is on it. One of `"waiting"`, `"accepted"`, `"rejected"`, `"offered"`, `"expired"`. `null` when the member is not on the waitlist.
`registered`	Boolean	`true` if the member is a registered attendee of the meeting.
`registered_at`	String \| null	When the member registered (ISO 8601), or `null` if not registered.

`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.
404 Not Found
- { "error": "User not found on HeyPeers" } when no member matches the supplied idp_id.

Notes

The list combines meetings the member is registered for and meetings they are waitlisted for, filtered to those that have not yet ended and are not canceled or completed.
waiting_status is only populated when the meeting has a waitlist enabled and the member is queued for it; otherwise it is null.
A meeting can appear with registered: false and a non-null waiting_status when the member is on the waitlist but does not yet hold a confirmed seat.
Responses are paginated. The defaults are items=10 and page=1.
To list every upcoming meeting for the organization rather than a single member, use the Upcoming Meetings endpoint.