ElearnHere API Documentation

This document provides a comprehensive guide for using the ElearnHere API. The API allows you to interact with groups, courses, users, and other resources within the ElearnHere learning management system.

Base URL

All API endpoints use the same base URL: https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/

Authentication

Most endpoints require authentication using basic authentication.

Endpoints

Groups

Get All Groups

Retrieves all groups that the authenticated user has administrator access to.

GET /groups

Parameters:

Parameter	Type	Description	Default
per_page	integer	Number of items per page	100
page	integer	Current page number	1

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "groups": [
      {
        "id": 123,
        "title": "Group Name",
        "seats": {
          "total": 100,
          "enrolled": 75,
          "remaining": 25
        },
        "links": {
          "users": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users",
          "courses": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/courses"
        }
      }
    ],
    "result_count": 1
  },
  "message": "Groups retrieved successfully."
}

Get Group Users

Retrieves users belonging to a specific group.

GET /groups/{id}/users

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
per_page	integer	Number of items per page	100
page	integer	Current page number	1
include_inactive	boolean	Whether to include inactive users	true
completion_date_from	string	Filter users who completed courses after this date (format: YYYY-MM-DD)	null
completion_date_to	string	Filter users who completed courses before this date (format: YYYY-MM-DD)	null

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "users": [
      {
        "id": 456,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "code": "CODE-12345678",
        "progress": [
          {
            "course_id": 48115,
            "course_title": "2025 – Blended Emergency First Aid At Work",
            "questions": {
              "completed": 0,
              "total": 49,
              "percent": 0
            },
            "status": "not_started",
            "started_date": null,
            "completed_date": null,
            "last_active": null
          }
        ],
        "status": "active",
        "links": {
          "self": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users/456",
          "courses": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users/456/courses",
          "deactivate": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users/456/deactivate"
        }
      }
    ],
    "result_count": 1,
    "filters": {
      "include_inactive": true,
      "filter_links": {
        "all": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users?include_inactive=true&per_page=100&page=1",
        "active": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users?include_inactive=false&per_page=100&page=1",
        "clear_date_filter": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users?include_inactive=true&per_page=100&page=1"
      },
      "completion_date_from": "2023-01-01",
      "completion_date_to": "2023-12-31"
    },
    "actions": {
      "bulk_activate": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users/bulk/reactivate",
      "bulk_deactivate": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users/bulk/deactivate"
    }
  },
  "message": "Group users retrieved successfully."
}

Get Group Courses

Retrieves all courses associated with a specific group.

GET /groups/{id}/courses

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "courses": [
      {
        "id": 789,
        "title": "Course Name"
      }
    ],
    "result_count": 1,
    "links": {
      "users": "https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users"
    }
  },
  "message": "Group courses retrieved successfully."
}

Add Users to Group

Adds one or more users to a specific group.

POST /groups/{id}/users

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
users	array	Array of user information to add to the group	Required

Request Body:

{
  "users": [
    {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "send_notification": true
    }
  ]
}

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "added_users": [
      {
        "id": 456,
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "code": "CODE-12345678",
        "enrolled_courses": 2
      }
    ],
    "failed_users": [],
    "added_count": 1,
    "failed_count": 0
  },
  "message": "1 user(s) added to the group. 0 user(s) failed."
}

Deactivate User in Group

Deactivates a user in a specific group.

PUT /groups/{id}/users/{user_id}/deactivate

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
user_id	integer	User ID to deactivate	Required

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "user": {
      "id": 456,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "inactive",
      "deactivated_on": "2023-01-01 12:00:00"
    }
  },
  "message": "User successfully deactivated."
}

Reactivate User in Group

Reactivates a previously deactivated user in a specific group.

PUT /groups/{id}/users/{user_id}/reactivate

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
user_id	integer	User ID to reactivate	Required

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "user": {
      "id": 456,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "active",
      "reactivated_on": "2023-01-01 12:00:00"
    }
  },
  "message": "User successfully reactivated."
}

Diagnose Group

Retrieves diagnostic information for a specific group.

GET /groups/{id}/diagnose

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "table_exists": true,
    "columns": {
      "id": {
        "type": "bigint(20)",
        "null": "NO",
        "key": "PRI",
        "default": null
      }
    },
    "row_count": 100,
    "sample_rows": [],
    "group_code_id": 123,
    "group_has_codes": true,
    "group_code_count": 75,
    "group": {
      "id": 123,
      "title": "Group Name",
      "meta": {
        "_ulgm_code_group_id": "123",
        "_ulgm_code_prefix": "CODE",
        "_ulgm_total_seats": "100"
      }
    },
    "user_count": 75
  },
  "message": "Diagnostic information retrieved successfully."
}

Bulk Deactivate Users

Deactivates multiple users in a specific group in a single request.

POST /groups/{id}/users/bulk/deactivate

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
user_ids	array	Array of user IDs to deactivate	Required

Request Body:

{
  "user_ids": [456, 789]
}

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "deactivated_users": [
      {
        "id": 456,
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "status": "inactive",
        "deactivated_on": "2023-01-01 12:00:00"
      }
    ],
    "failed_deactivations": [],
    "success_count": 1,
    "failed_count": 0
  },
  "message": "1 user(s) successfully deactivated. 0 user(s) failed."
}

Bulk Reactivate Users

Reactivates multiple users in a specific group in a single request.

POST /groups/{id}/users/bulk/reactivate

Parameters:

Parameter	Type	Description	Default
id	integer	Group ID	Required
user_ids	array	Array of user IDs to reactivate	Required

Request Body:

{
  "user_ids": [456, 789]
}

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "group_id": 123,
    "group_title": "Group Name",
    "reactivated_users": [
      {
        "id": 456,
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "status": "active",
        "reactivated_on": "2023-01-01 12:00:00"
      }
    ],
    "failed_reactivations": [],
    "success_count": 1,
    "failed_count": 0
  },
  "message": "1 user(s) successfully reactivated. 0 user(s) failed."
}

Courses

Get All Courses

Retrieves all courses.

GET /courses

Parameters:

Parameter	Type	Description	Default
per_page	integer	Number of items per page	100
page	integer	Current page number	1
orderby	string	Field to order by	"title"
order	string	Order direction (ASC or DESC)	"ASC"

Response:

{
  "status": 200,
  "success": true,
  "data": {
    "courses": [
      {
        "id": 789,
        "title": "Course Name"
      }
    ],
    "result_count": 1
  },
  "message": "Courses retrieved successfully."
}

Credit

Get Credit Status

Retrieves the credit status.

GET /credit/status

Response:

{
  "status": 200,
  "success": true,
  "data": [],
  "message": "Credit retrieved successfully."
}

Error Handling

The API returns appropriate HTTP status codes and error messages when requests fail.

Common Error Codes:

400 Bad Request: The request was invalid or cannot be served.
403 Forbidden: The request is valid, but the server is refusing action due to lack of permissions.
404 Not Found: The requested resource could not be found.
500 Internal Server Error: The server encountered an unexpected condition.

Example Error Response:

{
  "code": "unauthorized_access",
  "message": "You do not have permission to access this group.",
  "data": {
    "status": 403
  }
}

Pagination

Most endpoints that return lists of resources support pagination. The following pagination parameters are available:

per_page: Number of items to return per page.
page: Page number to return.

The response includes pagination information:

{
  "status": 200,
  "success": true,
  "data": {
    "result_count": 100,
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_pages": 10
    }
  }
}

Date Filtering

The Group Users endpoint supports filtering by course start and completion dates. This allows you to retrieve only users who have started or completed courses within specific date ranges.

Date Filter Parameters:

completion_date_from: Filter users who completed a course on or after this date (format: YYYY-MM-DD)
completion_date_to: Filter users who completed a course on or before this date (format: YYYY-MM-DD)

Example Usage:

To get all users who completed a course in January 2023:

GET https://dev.elearnhere.co.uk/wp-json/elearnhere/v2/groups/123/users?completion_date_from=2023-01-01&completion_date_to=2023-01-31

This allows you to find all users who have completed courses within a specific date range.

Progress Data Structure

The user progress data has been enhanced to include detailed information about course progress, including start and completion dates:

"progress": [
  {
    "course_id": 48115,
    "course_title": "2025 – Blended Emergency First Aid At Work",
    "questions": {
      "completed": 0,
      "total": 49,
      "percent": 0
    },
    "status": "not_started", // Possible values: "not_started", "in_progress", "completed"
    "started_date": null, // Date when the user first accessed the course (format: YYYY-MM-DD HH:MM:SS)
    "completed_date": null, // Date when the user completed the course (format: YYYY-MM-DD HH:MM:SS)
    "last_active": null // Date when the user last interacted with the course (format: YYYY-MM-DD HH:MM:SS)
  }
]