Peer Supporters

Retrieve a paginated list of the peer supporters in your organization. The endpoint returns the org-specific peer supporter profile (bio, motivation, recovery status, specialties, rating) and, when the same person is also a platform-level peer supporter on HeyPeers, includes that supplementary information under a nested independent_peer_supporter object.

Use this endpoint to power a “Meet our peer supporters” page on your website, a directory, or any internal tool that needs structured access to your peer supporter roster.

Endpoint

GET: /api/v2/organizations/:organization_id/peer_supporters

Authentication

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

Optional Query Parameters

Name	Type	Default	Description
`q`	String	—	Case-insensitive substring match against the user’s first name, last name, or the org member’s bio.
`search`	String	—	Alias for `q`.
`page`	Integer	`1`	Page number (1-indexed).
`items`	Integer	`10`	Items per page. Clamped to `1..100`.

Example Request


GET /api/v2/organizations/5/peer_supporters?q=jane&page=1&items=20
Authorization: Bearer <token>
Accept: application/json


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

Success Response

200 OK


{
  "current_page": 1,
  "items": 20,
  "total_items": 47,
  "total_pages": 3,
  "peer_supporters": [
    {
      "id": 812,
      "user_id": 4501,
      "first_name": "Jane",
      "last_name": "Doe",
      "full_name": "Jane D.",
      "bio": "Certified peer supporter focused on grief and loss.",
      "motivation": "Helping others find their footing after loss.",
      "recovery_status": "10 years in recovery from substance use.",
      "time_zone": "America/Los_Angeles",
      "profile_image_url": "https://heypeers-assets.s3.amazonaws.com/users/avatars/medium/4501.png",
      "profile_image_thumb_url": "https://heypeers-assets.s3.amazonaws.com/users/avatars/thumb/4501.png",
      "status": "approved",
      "specialties": ["depression_counseling", "ptsd", "suicide_prevention"],
      "rating": 4.8,
      "feedback_count": 32,
      "is_independent_peer_supporter": true,
      "independent_peer_supporter": {
        "about": "I've been a peer supporter on HeyPeers since 2022.",
        "rating": 4.9,
        "ratings_count": 118,
        "preference": {
          "languages": ["English", "Spanish"],
          "peer_support_interests": ["Grief", "PTSD"],
          "availability": true,
          "greetings": "Hi, I'm Jane. Happy to meet you.",
          "motivation": "Paying forward the support I received.",
          "recovery_status": "10 years in recovery."
        }
      }
    },
    {
      "id": 813,
      "user_id": 4502,
      "first_name": "Sam",
      "last_name": "Lee",
      "full_name": "Sam L.",
      "bio": "Group facilitator and peer supporter.",
      "motivation": null,
      "recovery_status": null,
      "time_zone": "America/New_York",
      "profile_image_url": "https://ssl.gstatic.com/accounts/ui/avatar_2x.png",
      "profile_image_thumb_url": "https://ssl.gstatic.com/accounts/ui/avatar_2x.png",
      "status": "approved",
      "specialties": ["alcohol_abuse"],
      "rating": 0.0,
      "feedback_count": 0,
      "is_independent_peer_supporter": false,
      "independent_peer_supporter": 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 peer supporters across all pages.
`total_pages`	Integer	Total number of pages.
`peer_supporters`	Array	Peer supporter records on the current page.

Peer supporter object

Field	Type	Source	Description
`id`	Integer	OrganizationMember	The organization member id. Stable identifier for this peer supporter within your organization.
`user_id`	Integer	User	The underlying HeyPeers user id.
`first_name`	String	User
`last_name`	String	User
`full_name`	String	User	Display name (first name + last initial).
`bio`	String	OrganizationMember	Org-specific bio (max 600 chars).
`motivation`	String	OrganizationMember	Org-specific “why I’m a peer supporter” statement.
`recovery_status`	String	OrganizationMember	Org-specific recovery summary.
`time_zone`	String	User	IANA time zone.
`profile_image_url`	String	User	URL for the medium (300x300) avatar. Falls back to a default avatar if unset.
`profile_image_thumb_url`	String	User	URL for the thumb (100x100) avatar. Falls back to a default avatar if unset.
`status`	String	OrganizationMember	`pending` or `approved`.
`specialties`	Array<String>	OrganizationMember	Subset of `alcohol_abuse`, `depression_counseling`, `family_abuse`, `ptsd`, `substance_abuse`, `suicide_prevention`.
`rating`	Float	OrganizationMember	Average org-level rating.
`feedback_count`	Integer	OrganizationMember	Number of org-level feedback ratings received.
`is_independent_peer_supporter`	Boolean	PeerSupporter	True when the same user also holds an active platform-level peer supporter profile on HeyPeers.
`independent_peer_supporter`	Object \| null	PeerSupporter	Platform-level peer supporter details. `null` when `is_independent_peer_supporter` is false or the independent profile is closed.

`independent_peer_supporter` object

Field	Type	Source	Description
`about`	String	User	Platform-level bio (separate from the org-level `bio`).
`rating`	Float	PeerSupporter	Average rating from platform-level engagements.
`ratings_count`	Integer	PeerSupporter	Number of platform-level ratings received.
`preference`	Object	Preference	User-level preferences (see below).

`independent_peer_supporter.preference` object

Field	Type	Description
`languages`	Array<String>	Spoken languages.
`peer_support_interests`	Array<String>	Topics the peer supporter is interested in covering.
`availability`	Boolean	Whether the peer supporter is currently accepting requests at the platform level.
`greetings`	String	Public greeting / introduction line.
`motivation`	String	Platform-level motivation statement.
`recovery_status`	String	Platform-level recovery summary.

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.

Notes

Results are filtered to organization members who hold the peer_supporter org role.
Responses are paginated. The defaults are items=10 and page=1.
The independent_peer_supporter lookup is scoped to platform-level peer supporters only (PeerSupporter records with no organization_id).
Org-level fields (bio, motivation, recovery_status, rating, feedback_count) and independent-level fields are maintained separately so you can choose which to display. Top-level fields describe the peer supporter within your organization; the nested object describes their broader HeyPeers presence.