Searching & Listing Groups

Search by name, pagination, filtering

Written By jazilkalim

Last updated 11 months ago

What is Group Search?

Group search and listing operations allow you to find and browse groups in your CampusMindAI tenant.

Why Search and List Groups?

Quick Lookup: Find groups by name
Administration: Review group structure
Audit: Verify group configuration

Search Groups

Search for groups by name using a search term.

Endpoint Details

Method: GET
URL: {{baseURL}}/api/v1/groups?search_term=<term>
Authentication: Required (JWT Bearer token)

Query Parameters

			ParameterTypeRequiredDescription
`search_term`	string	Yes	Search term for group name

Example Request

curl -X GET "https://<baseURL>/api/v1/groups?search_term=CS101" \
  -H "Authorization: Bearer <jwt-token>"

Response

Status Code: 200 OK

{
  "current_page": 1,
  "next_page": 0,
  "total_pages": 1,
  "total_records": 3,
  "limit": 10,
  "search_term": "CS101",
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Response Fields

		FieldTypeDescription
`current_page`	integer	Current page number
`next_page`	integer	Next page (0 if no more pages)
`total_pages`	integer	Total pages of results
`total_records`	integer	Total matching groups
`search_term`	string	Search term used
`groups`	array	Array of matching groups

List Groups

Retrieve a paginated list of all groups in your tenant.

Endpoint Details

Method: POST
URL: {{baseURL}}/api/v1/list_group
Authentication: Required (JWT Bearer token)

Request Body

			ParameterTypeRequiredDescription
`page`	integer	Yes	Page number (starts at 1)
`limit`	integer	Yes	Groups per page

Example Request

curl -X POST "https://<baseURL>/api/v1/list_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response

Status Code: 200 OK

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47,
  "limit": 10,
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Group Object Fields

		FieldTypeDescription
`group_id`	integer	Unique group identifier
`group_name`	string	Group name
`group_description`	string	Group description
`group_updated_at`	string	Last update timestamp (ISO 8601)
`group_tenant_global`	string	"0"=local, "1"=global
`group_created_by`	string	Creator's email
`group_created_by_id`	string	Creator's user ID
`role_id`	integer	Associated role (1=Student, 2=Instructor, 3=Admin)

Search Tips

Partial matching: Search term matches anywhere in group name
Case insensitive: Search is not case-sensitive
Common patterns: Use course codes, semesters, or department names

Pagination

Navigate through pages by incrementing the page parameter:

# Page 1
{"page": 1, "limit": 10}

# Page 2
{"page": 2, "limit": 10}

Continue until next_page is 0.

Error Responses

	Status CodeDescription
`400 Bad Request`	Invalid parameters (page < 1, limit < 1)
`401 Unauthorized`	Invalid or missing JWT token
`500 Internal Server Error`	Server error

Troubleshooting

No Search Results

Solutions:

Verify search term spelling
Try broader search terms
Use list_group to see all available groups

Empty Group List

Solutions:

Start with page 1
Verify groups exist in tenant
Check user permissions

Was this helpful?

Still need help? Share an idea