Skip to content

Manage staff accounts

Staff are the people in your organisation who work with learners: tutors, tutor managers, client admins, and report viewers. The /v1/staff endpoints let you provision and maintain those accounts from your own system, so a tutor a learner needs no longer has to be created by hand in the app first. A staff member may hold more than one role at once.

All calls use the base URL https://api.uk.cognassist.com and a bearer token (see Getting started). Your credentials are scoped to your organisation, so these endpoints only ever act on your organisation's staff.

Reach for these endpoints when you want your HR or MIS system to own staff onboarding and offboarding, or to reconcile your tutor list against Cognassist the same way you reconcile learners. If you only ever manage a handful of tutors, provisioning them in the app is still perfectly fine.

  • Create a staff member with POST /v1/staff, supplying roles (any of Tutor, TutorManager, ClientAdmin, ReportViewer). It returns 201 Created with the new userId. When the roles include Tutor, you can pass tutorManagerEmails to assign that tutor's managers in the same call; those emails must already resolve to tutor managers.
  • List staff with GET /v1/staff, paged like the learner list. Pass an optional role to filter to a single role. Learners are never included.
  • Read one with GET /v1/staff/{userId} or GET /v1/staff/{email}. A target that does not resolve to a staff member returns 404: a learner email, an unknown email, or an unknown or already-deleted userId. The read, update, and delete routes all behave the same way, so a staff member you have just deleted reads as 404 on any follow-up call by id or email.
  • Update with PUT /v1/staff/{userId} or PUT /v1/staff/{email}. The roles you send replace the staff member's current roles. The id route can change the email; the email route preserves it (it is the routing handle).
  • Delete with DELETE /v1/staff/{userId} or DELETE /v1/staff/{email}, returning 204 No Content.

A staff member who still has active assignments cannot be removed cleanly: deleting a tutor who is the primary tutor on any active learner, or removing the Tutor role from them, is rejected with a 400, as is deleting a tutor manager who still has tutors reporting to them. Reassign the affected learners or tutors first. Removing a tutor who holds only secondary assignments succeeds and drops those assignments.

Provisioning staff is a prerequisite for creating learners: a learner's primaryTutorEmail must resolve to a tutor who already exists at the time of the create call. See Create and manage learners for that ordering.

For the full request and response shapes, see the staff endpoints in the API reference.