Online Programs Participants API: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Enroll members in online programs

Your app allows site owners to enroll members in their online programs through various payment models. Members can join for free, pay once, subscribe to a plan, or be manually added by the program owner.

To enroll a member in an online program:

1. Call Get Member to verify the member exists and retrieve their details.
2. Call Get Program to confirm the program is available and check enrollment requirements.
3. Call Create Participant with the required memberId, programId, and enrollmentInfo.pricingType. Include the payment details field that corresponds to the pricing type, if applicable:
   Copy

4. Handle any premium plan limitations by upgrading the site plan if the PREMIUM_PLAN_REQUIRED error is returned.
5. Optionally request the PROGRESS field to get initial progress information for the new participant.

Track participant progress and completion

Your app monitors how participants advance through program content and uses their calculated progress status to identify completion or failure.

To track participant progress through a program:

1. Call Get Participant with fields=["PROGRESS"] to retrieve current progress information including totalStepsCompleted and completionPercentage.
2. Monitor the participant's lastActivityDate to track engagement.
3. When a participant completes all required steps, their progressStatus automatically changes to COMPLETED.
4. If a participant misses the program deadline, their progressStatus changes to FAILED.
5. Call Query Participants with progress status filters to get lists of participants by completion status:
   Copy

Display program participation statistics

Your app displays participation counts for one or more programs.

To retrieve participation statistics:

1. Call Get Participation Stats with 1 to 100 program IDs.
2. Use participantsCount for participants with a joined or suspended enrollment, including participants who completed or failed the program.
3. Use autoRemovedCount separately for participants automatically removed when the program duration ended.
4. Use this method for site-wide counts. In contrast, Search Participants and its aggregations only include participant records that the caller is authorized to access.

Manage participant lifecycle and status changes

Your app handles various participant status transitions based on program rules, payment issues, and administrative actions.

To manage participant status changes:

1. Monitor enrollmentStatus and progressStatus through domain events or periodic queries.
2. For payment-related suspensions, call Update Participant to change enrollmentStatus to SUSPENDED when payment plans expire.
3. For administrative removals, call Delete Participant to remove them.
4. For voluntary departures, call Delete Participant from the member's call scope. The participant's enrollment status is set to LEFT.
5. Use Get Access Status to check if participants are blocked from accessing programs due to site limitations.
6. Track status history through the updatedDate field and domain events for audit purposes.

Issue certificates to program graduates

Your app automatically issues certificates to participants who successfully complete programs that offer certificate rewards.

To issue a certificate to a qualified participant:

1. Verify the participant has progressStatus set to COMPLETED by calling Get Participant.
2. Call Get Program to confirm the program has a certificate reward configured.
3. Call Issue Certificate as a site admin to generate the certificate:
   Copy

4. Handle precondition errors:
   • PARTICIPANT_NOT_ACTIVE: Participant must be active or finished.
   • NO_CERTIFICATE_REWARD: Program must be configured with certificate rewards.
   • PARTICIPANT_NOT_COMPLETED_PROGRAM: The participant hasn't completed all required steps in the program.
5. The certificate issueDate is automatically set when successfully issued.
6. Call Get Certificate Download URL with the participant ID. The method resolves the most recently issued certificate. Rendering is asynchronous, so retry after receiving CERTIFICATE_NOT_READY.
7. Give the returned downloadUrl to the participant. Request a new URL after expirationDate instead of storing the URL permanently.
8. If the certificate document has expired, issue the certificate again before requesting another download URL.
9. Notify the participant about their certificate through your app's notification system.

Perform bulk participant operations

Your app efficiently manages large numbers of participants through bulk operations for enrollment, tagging, and member addition.

Part 1: Bulk participant creation

To create multiple participants at once:

1. Prepare a list of up to 100 participants, all for the same program.
2. Call Bulk Create Participants with the participant list:
   Copy

3. Handle bulk operation results, checking itemMetadata for individual success or failure status.
4. Process any premium plan limitations that may affect the bulk operation.

Part 2: Bulk member addition

To add many site members to a program:

1. Call Bulk Create Participants For All Members with the target programId.
2. Optionally specify excludeMemberIds to skip certain members.
3. The operation creates participants with JOINED enrollment status and ADDED_MANUALLY pricing type.
4. Pass the returned jobId to Get Async Job to track the asynchronous operation.

Part 3: Bulk tag management

To update tags for multiple participants:

1. For specific participants, call Bulk Update Participant Tags with up to 100 participant IDs.
2. For filtered participants, call Bulk Update Participant Tags By Filter with a WQL filter.
3. Specify tags to assignTags and/or unassignTags in the same operation.
4. Pass the returned jobId to Get Async Job for filter-based operations.