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. You can also pass locations; see Give a tutor locations. firstName and lastName follow the same name rule as learners: letters, spaces, hyphens, apostrophes and full stops only.
  • 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). A changed firstName or lastName is checked against the name rule; an unchanged one is accepted as stored.
  • 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.

Give a tutor locations

A tutor can hold up to 10 locations, the sites they work at. They describe the tutor for your own reporting: they do not decide which learners the tutor sees, and they do not limit a learner's location. Only a staff member with the Tutor role can hold locations; for anyone else these routes return 400.

  • Add locations with POST /v1/staff/{userId}/locations, sending {"locations": ["Bedford Campus", "Ripon"]}. Adding is additive: locations the tutor already holds are left alone, and any location your organisation does not have yet is created. Names match case-insensitively. You get 204 No Content.
  • Remove a location with DELETE /v1/staff/{userId}/locations?name=Ripon. This removes it from that tutor only; your organisation keeps it. Removing a location the tutor does not hold succeeds and changes nothing.
  • Read a tutor's locations with GET /v1/staff/{userId}/locations, as an id and a name each. GET /v1/staff/{userId} also returns them, as a read-only locations list of names.
  • Give them on create by sending locations on POST /v1/staff with the Tutor role. More than 10 locations is a 400 before anything is created. A name that breaks the location rules, or a tag's name, is a 400 naming locations, with no staff member created, so you can correct the names and resend. Names accepted before the refused one may already have been added to your locations; delete any you do not want with DELETE /v1/locations. A 403 means locations are not enabled for your organisation.

PUT /v1/staff/... never changes a tutor's locations. Removing the Tutor role, or deleting the staff member, removes all of them.