User Segments API

User Segments API

Info
Note: In this system, a "Cohort" is a group of users, similar to a "User Segment".

core_cohort_add_cohort_members

This function adds one or more users to a specified cohort.

Let's review the POST parameters for this function:

  1. Required Parameters:
    • The entire members object is required to identify the user and the cohort.
    • members[0][cohorttype][type]= string (Required: How to identify the cohort. Use 'id' for the numeric ID or 'idnumber' for the alphanumeric ID.)
    • members[0][cohorttype][value]= string (Required: The actual ID or idnumber of the cohort.)
    • members[0][usertype][type]= string (Required: How to identify the user. Use 'id' for the numeric user ID or 'username' for the alphanumeric username.)
    • members[0][usertype][value]= string (Required: The actual ID or username of the user.)

cURL Command Example (Adding a User to a Cohort):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_cohort_add_cohort_members" \
-d "members[0][cohorttype][type]=idnumber" \
-d "members[0][cohorttype][value]=FALL2025-ENG101" \
-d "members[0][usertype][type]=username" \
-d "members[0][usertype][value]=janedoe"


core_cohort_delete_cohort_members

This function removes one or more users from a specified cohort.

Let's review the POST parameters for this function:

  1. Required Parameters:
    • members[0][cohortid]= int (Required: The numeric ID of the cohort.)
    • members[0][userid]= int (Required: The numeric ID of the user to be removed.)

cURL Command Example (Removing a User from a Cohort):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_cohort_delete_cohort_members" \
-d "members[0][cohortid]=45" \
-d "members[0][userid]=123"


core_cohort_create_cohorts

This function creates one or more new cohorts.

Let's review the POST parameters for this function:

  1. Required Parameters:
    • cohorts[0][categorytype][type]= string (Required: The context for the cohort. Use 'system' for site-level.)
    • cohorts[0][categorytype][value]= string (Required: The value for the context. If type is 'system', this can be 0 or 1.)
    • cohorts[0][name]= string (Required: The name of the cohort.)
    • cohorts[0][idnumber]= string (Required: A unique alphanumeric ID for the cohort.)
  2. Optional Parameters:
    • cohorts[0][description]= string (Optional: A description for the cohort.)
    • cohorts[0][visible]= int (Optional: Set to 1 for visible, 0 for hidden. Defaults to 1.)

cURL Command Example (Creating a New Cohort):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_cohort_create_cohorts" \
-d "cohorts[0][categorytype][type]=system" \
-d "cohorts[0][categorytype][value]=1" \
-d "cohorts[0][name]=Faculty Members" \
-d "cohorts[0][idnumber]=FACULTY" \
-d "cohorts[0][description]=All official faculty staff"


core_cohort_delete_cohorts

This function deletes one or more cohorts based on their IDs.

Let's review the POST parameters for this function:

  1. Required Parameter:
    • cohortids[0]= int (Required: The numeric ID of the cohort to delete. Pass multiple to delete more than one.)

cURL Command Example (Deleting a Cohort):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_cohort_delete_cohorts" \
-d "cohortids[0]=45"


core_cohort_get_cohorts

This function retrieves information about one or more cohorts.

Let's review the POST parameters for this function:

  1. Optional Parameter:
    • cohortids[0]= int (Optional: The numeric ID of a cohort to retrieve. If omitted, the system may return all cohorts.)

cURL Command Example (Getting Specific Cohorts):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_cohort_get_cohorts" \
-d "cohortids[0]=45" \
-d "cohortids[1]=46"

    • Related Articles

    • User API

      core_user_create_users We advise the use of a developer to help you setup your API connection. This example shows how to create new users. Let's review the POST parameters for this function: Required Parameters: users[0][username]= string (Required: ...

    • Grades API

      gradereport_overview_get_course_grades This function retrieves an overview of all final course grades for a specific user. Let's review the POST parameters for this function: Optional Parameter: userid= int (Optional: The numeric ID of the user. If ...

    • Finding Pluto LMS IDs

      USER IDS To find a User ID: Go to "Site admin" → "User Management" → "View all site users", then select the applicable User Profile. The ID can be found in the browser URL: COURSE IDS To find a Course ID: Go to the applicable Course. The ID can be ...

    • Generate your API Key

      Step 1: Click on "Site admin" > "Integrations" > "Manage tokens": Step 2: Click on "Create Token": Step 3: (1) Select the user you wish to give the API Token to, (2) Select "API" then (3) Save: Step 4: Share this token with the user or save it if ...

    • Setting Up Your API

      We advise the use of a developer to help you setup your API connection. We will offer an example of how to CREATE A NEW USER on your LMS using a cURL command. Let's review the required POST parameters for the core_user_create_users function: ...