Update Staff Member¶

Updates a staff member and returns the updated record.

Endpoint¶

PATCH /v2/staff/{staff_id}

Path Parameters¶

Parameter	Type	Required	Description
`staff_id`	string	Yes	The staff member's id.

Query Parameters¶

Parameter	Type	Required	Description
`onboarding`	boolean	No	Treat the path id as an onboarding_user_id rather than an operational id. Required to address a staff member that has not been published yet; also forces the onboarding path on PATCH/DELETE.

Request Body¶

Parameter	Type	Required	Description
`first_name`	string	No
`middle_name`	string or null	No
`last_name`	string	No
`email`	string	No
`mobile`	string or null	No
`clinic_ids`	array of string	No	Operational clinic ids for published staff; onboarding clinic ids for a not-yet-published record.
`role`	string	No	The staff member's role. Clinical roles are providers, not staff. One of `ADMIN`, `MANAGER`, `RECEPTIONIST`, `BILLER`, `TECH`.
`roles`	array of string	No	Roles for an onboarding-managed staff member — set only when creating or updating through onboarding. One of `ADMIN`, `JUNIOR_DOCTOR`, `STUDENT`, `RECEPTIONIST`, `TECH`, `BILLER`. `JUNIOR_DOCTOR` and `STUDENT` require `is_cosign_required`; `supervising_provider_id` is required when `is_cosign_required` is `true` and rejected otherwise. Only `JUNIOR_DOCTOR` may carry `npi`; only supervised roles accept `schedule`. `TECH` cannot combine with other roles; `JUNIOR_DOCTOR` combines only with `STUDENT`.
`is_cosign_required`	boolean	No	Whether this staff member's actions require a supervising provider's cosign. Required (and must be `true`) for `JUNIOR_DOCTOR` and `STUDENT`.
`supervising_provider_id`	string or null	No	The supervising provider, required for a supervised role.
`npi`	string or null	No
`schedule`	array	No	Working-hours entries for a supervised role (`JUNIOR_DOCTOR` / `STUDENT`), passed through from onboarding's own shape.
`access_revoked`	boolean	No	Whether this staff member's onboarding access has been revoked.

Request¶

curl --location '{base_url}/v2/staff/7106' \
  --request PATCH \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '{
  "first_name": "Morgan",
  "middle_name": null,
  "last_name": "Delgado",
  "email": "m.delgado@example.com",
  "mobile": "+1-555-0155",
  "clinic_ids": [
    "5831"
  ],
  "role": "RECEPTIONIST",
  "roles": [
    "JUNIOR_DOCTOR"
  ],
  "is_cosign_required": true,
  "supervising_provider_id": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
  "npi": "1740398215",
  "schedule": null,
  "access_revoked": false
}'

Response¶

Success Response¶

Code: 200 OK

{
  "id": "7106",
  "onboarding_user_id": "f14a2c88-6d31-4b09-9e77-3c8d1a52f9e6",
  "role": null,
  "roles": [
    "JUNIOR_DOCTOR"
  ],
  "first_name": "Morgan",
  "middle_name": null,
  "last_name": "Delgado",
  "email": "m.delgado@example.com",
  "mobile": "+1-555-0155",
  "clinic_ids": [
    "5831"
  ],
  "status": "ACTIVE",
  "is_cosign_required": true,
  "supervising_provider_id": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
  "npi": "1740398215",
  "schedule": null,
  "access_revoked": false,
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

Response Fields¶

Field	Type	Description
`id`	string or null	The staff member's id.
`onboarding_user_id`	string or null	The staff member's onboarding-record UUID. Present when this staff member is managed through onboarding.
`role`	string or null	The staff member's role. Clinical roles are providers, not staff.
`roles`	array of string	Roles for an onboarding-managed staff member — set only when creating or updating through onboarding. One of `ADMIN`, `JUNIOR_DOCTOR`, `STUDENT`, `RECEPTIONIST`, `TECH`, `BILLER`. `JUNIOR_DOCTOR` and `STUDENT` require `is_cosign_required`; `supervising_provider_id` is required when `is_cosign_required` is `true` and rejected otherwise. Only `JUNIOR_DOCTOR` may carry `npi`; only supervised roles accept `schedule`. `TECH` cannot combine with other roles; `JUNIOR_DOCTOR` combines only with `STUDENT`.
`first_name`	string or null
`middle_name`	string or null
`last_name`	string or null
`email`	string or null
`mobile`	string or null
`clinic_ids`	array of string	Operational clinic ids for published staff; onboarding clinic ids for a not-yet-published record.
`status`	string	`ACTIVE`/`INACTIVE` for published staff; `ONBOARDING` for an unpublished onboarding record, `REVOKED` once access is revoked before publish.
`is_cosign_required`	boolean	Whether this staff member's actions require a supervising provider's cosign. Required (and must be `true`) for `JUNIOR_DOCTOR` and `STUDENT`.
`supervising_provider_id`	string or null	The supervising provider, required for a supervised role.
`npi`	string or null
`schedule`	any	Working-hours entries for a supervised role (`JUNIOR_DOCTOR` / `STUDENT`), passed through from onboarding's own shape.
`access_revoked`	boolean	Whether this staff member's onboarding access has been revoked.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`409 Conflict`	`conflict`	The record conflicts with existing state — see the endpoint's notes.
`412 Precondition Failed`	`precondition_failed`	`If-Match` is stale. Re-read the resource and retry.
`423 Locked`	`locked`	The organisation has a publish in progress. Retry once it finishes.
`428 Precondition Required`	`precondition_required`	`If-Match` is required on this write.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

PATCH is a JSON Merge Patch (RFC 7386): an omitted field is left alone, an explicit null clears it, and an array replaces the existing one wholesale.
A staff member with an onboarding_user_id routes this update through onboarding, under the same field rules as create.
access_revoked: true has the same effect as DELETE; set it back to false to restore access.