Update a user
Updates profile fields and optional institution membership demographics for a user in your integration’s institution. Profile and code are saved in one transaction with an audit entry for a code change. Partial updates are supported (absent = unchanged, null or "" clears code). Whitespace-only code is 422. Duplicate code returns 409 with existingUserId when that user is a member of this institution.
Email: this is the only users endpoint that starts a login-email change. Never-logged-in users reuse rewriteNeverLoggedInLoginEmail only after the profile and membership transaction commits. A 409 from that post-commit rewrite (email already taken) arrives after the profile and code changes have committed; the login email itself stays unchanged. Clerk users go through ensureClerkLoginEmailChange: a confirmation mail is sent and User.email updates after the user verifies. A differing email is 409 when the user has memberships in other institutions. Change the email here; PUT /users ignores a differing email on the update path.
No-op: unchanged fields (including a case-insensitive same code) are not written. No updatedAt bump and no UPDATED audit row.
/users/{id}AuthorizationBasic auth · headerrequiredBasic Auth with clientId as username and clientSecret as password
idstringrequiredapplication/jsonfirstNamestringlastNamestringemailstring<email>imagestring<uri> | nullProfile image URL as stored; no transcoding. null or an empty string clears the stored image.
codestring | nullInstitution membership code. Absent = unchanged. null or "" clears the code. Whitespace-only is 422, the same as POST and GET. A non-empty value is trimmed, max 191, and must match user_code_format when configured. Case-insensitive under the database collation.
preferredNamestringdateOfBirthstring<date>genderstringMALEFEMALEDIVERSEnationalitiesstring[]birthNamestringcountryOfBirthstringplaceOfBirthCitystringUpdated user
dataUserrequiredShow propertiesHide properties
idstringrequirednamestringrequiredemailstring<email>requiredimagestring | nullrequiredURL as stored; no transcoding, resolution, or format conversion.
codestring | nullrequiredInstitution membership code. One namespace per institution across students, staff, lecturers, and badge numbers. Unique per institution. Trimmed on write; empty becomes none. Case-insensitive under the database collation (FHM-1 equals fhm-1). When the institution has user_code_format, writes must match that format.
activityStatusUserActivityStatusrequiredShow propertiesHide properties
isActivebooleanrequiredisActiveFromstring<date-time> | nullrequiredisActiveUntilstring<date-time> | nullrequiredmetaResponseMetarequiredShow propertiesHide properties
requestIdstringrequiredtimestampstring<date-time>requiredversionstringrequiredv4watermarkstring<date-time>Present on GET /users?updatedSince= pages. Taken at the first page minus a 60s overlap. Bound into pagination.next_cursor. Use it as the next updatedSince after deduping by user id. Delivery is inclusive >= and at-least-once.
Bad Request
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredUnauthorized
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredNot Found
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredConflict — duplicate email or membership code (body includes existingUserId when known), a time-tracking session that is already running (activeSession), a time-tracking interval that overlaps an existing log (conflictingLog), idempotency key reused with a different body (idempotency_key_reused), or concurrent request with the same key still in progress (idempotency_key_in_progress)
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredUnprocessable Entity — validation or business rule error
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredToo Many Requests — 1000 requests per minute per institution. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (ISO-8601), and Retry-After (seconds).
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequiredInternal Server Error
typestringrequirederrorcodestringrequiredbad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_errortitlestringrequiredstatusintegerrequireddetailstringrequiredinstancestringerrorsobject[]Show propertiesHide properties
objectfieldstringmessagestringexistingUserIdstringPresent on 409 email or membership-code conflicts. The user id that already holds the email or code.
activeSessionobjectPresent on time-tracking start 409 when a session is already running. Stop this session, then retry start.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredconflictingLogobjectPresent on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.
Show propertiesHide properties
idstringrequiredstartTimestring<date-time>requiredendTimestring<date-time> | nullrequired