Retrieve program signups

Program signups are the records that connect participants to registration opportunities. This guide shows you how to list signups for a session, filter by user or status, and include related data like user details, form submissions, and payment information.

Before you begin

• Authentication — you need a valid API key.
• Programs & registration — understand how programs, registration opportunities, and signups relate.

1. List signups for a session

The most common starting point is fetching the roster for a specific registration opportunity. Filter by program_id to get all signups for that session. You can pass a single ID or comma-separated IDs to pull signups across multiple sessions at once.

curl -X GET "https://api.getcommunal.com/api/program_signups?filter[program_id]=101" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The response includes a paginated list of signup records, each with participant contact details, payment information, and foreign keys you can use for further lookups.

{
  "data": [
    {
      "id": 156,
      "program_id": 101,
      "user_id": 89,
      "guest_id": null,
      "additional_member_id": null,
      "associated_name": "John Doe",
      "associated_email": "john.doe@example.com",
      "participant_name": "Johnny Doe",
      "paid": 1,
      "amount_paid": 75,
      "payment_method": "Credit Card",
      "created_at": "2025-05-20T14:30:00.000000Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 30, "total": 12 }
}

To get signups across all sessions of a parent program, filter by the parent instead:

curl -X GET "https://api.getcommunal.com/api/program_signups?filter[program[parent_program_id]]=42" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

2. Filter by user, status, and search

You can narrow results to a specific participant, time window, or search term. Combine filters to match your exact needs.

To find all upcoming signups for a specific user:

curl -X GET "https://api.getcommunal.com/api/program_signups?filter[user_id]=89&filter[timeScope]=upcoming" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Available filters include:

• filter[user_id] — signups for a specific user. Non-managers can only query their own user ID.
• filter[query] — searches across program names, user names, emails, guest names, and additional member names.
• filter[timeScope] — upcoming (includes ongoing and active), past, or all.
• filter[status] — comma-separated time-based statuses: ongoing, upcoming, past.
• filter[event_start_date] — date range filter using filter[event_start_date][0]=2025-06-01&filter[event_start_date][1]=2025-08-31.
• filter[withTrashed] — set to true to include cancelled (soft-deleted) signups.

Note: The filter[status] and filter[timeScope] filters reflect the session's dates, not a signup-level status. A signup is "upcoming" when its session hasn't started yet.

3. Get a single signup

When you need full details for a specific registration — for a confirmation page, admin detail view, or to check payment status — fetch it by ID.

curl -X GET "https://api.getcommunal.com/api/program_signups/156" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The response includes participant details, payment information, and timestamps. The associated_name and associated_email fields resolve automatically from whichever participant type is on the signup — a user, guest, or additional family member.

4. Include related data

Use the include parameter to load related resources in a single request. This is essential for building roster views, confirmation screens, or reporting exports.

curl -X GET "https://api.getcommunal.com/api/program_signups?filter[program_id]=101&include=user,program,formSubmissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Available includes:

Important: Non-manager API keys can only view signups belonging to the authenticated user. Manager keys can view all signups and use the full set of filters.

What's next

• View attendance — track who showed up for each session
• Browse registration opportunities — find sessions and check capacity before viewing signups
• See the Program Signup endpoints in the API Reference for the complete list of fields and response shapes