Set primary organisation role

Sets or replaces the user’s primary institution-level role (no course scope).

PUT/users/{id}/primary-role

Authorization

AuthorizationBasic auth · headerrequired

Basic Auth with clientId as username and clientSecret as password

Path parameters

idstringrequired

Request body

requiredapplication/json

roleIdstringrequired

Responses

200

Primary role set

dataobjectrequired

Show properties

assignmentIdstring

userIdstring

roleIdstring

institutionIdstring

metaResponseMetarequired

Show properties

requestIdstringrequired

timestampstring<date-time>required

versionstringrequired

Allowed:v4

watermarkstring<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.

400

Bad Request

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties

idstringrequired

startTimestring<date-time>required

conflictingLogobject

Present 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 properties

idstringrequired

startTimestring<date-time>required

endTimestring<date-time> | nullrequired

401

Unauthorized

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties

idstringrequired

startTimestring<date-time>required

conflictingLogobject

Show properties

idstringrequired

startTimestring<date-time>required

endTimestring<date-time> | nullrequired

404

Not Found

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties

idstringrequired

startTimestring<date-time>required

conflictingLogobject

Show properties

idstringrequired

startTimestring<date-time>required

endTimestring<date-time> | nullrequired

429

Too Many Requests — 1000 requests per minute per institution. Includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (ISO-8601), and Retry-After (seconds).

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties

idstringrequired

startTimestring<date-time>required

conflictingLogobject

Show properties

idstringrequired

startTimestring<date-time>required

endTimestring<date-time> | nullrequired

500

Internal Server Error

typestringrequired

Allowed:error

codestringrequired

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error

titlestringrequired

statusintegerrequired

detailstringrequired

instancestring

errorsobject[]

Show properties

Array of object

fieldstring

messagestring

existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties

idstringrequired

startTimestring<date-time>required

conflictingLogobject

Show properties

idstringrequired

startTimestring<date-time>required

endTimestring<date-time> | nullrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Basic auth usernameBasic auth password

Remember on this deviceInclude my values in samples

Parameters

idpath*

Bodyapplication/json

roleIdstring*

Request

curl -X PUT 'https://fuxam.app/api/v4/users/string/primary-role' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "roleId": "string"
}'

const response = await fetch("https://fuxam.app/api/v4/users/string/primary-role", {
  method: "PUT",
  headers: {
    "Authorization": "Basic YOUR_CREDENTIALS",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"roleId\": \"string\"\n}"
});

import requests

response = requests.put(
    "https://fuxam.app/api/v4/users/string/primary-role",
    headers={
        "Authorization": "Basic YOUR_CREDENTIALS",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"roleId\": \"string\"\n}",
)

Response

{
  "data": {
    "assignmentId": "string",
    "userId": "string",
    "roleId": "string",
    "institutionId": "string"
  },
  "meta": {
    "requestId": "req_1234567890_abc",
    "timestamp": "2026-06-02T07:00:00.000Z",
    "version": "v4",
    "watermark": "2019-08-24T14:15:22Z"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "existingUserId": "string",
  "activeSession": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z"
  },
  "conflictingLog": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "existingUserId": "string",
  "activeSession": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z"
  },
  "conflictingLog": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "existingUserId": "string",
  "activeSession": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z"
  },
  "conflictingLog": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "existingUserId": "string",
  "activeSession": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z"
  },
  "conflictingLog": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z"
  }
}

{
  "type": "error",
  "code": "resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Course not found",
  "instance": "req_1234567890_abc",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "existingUserId": "string",
  "activeSession": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z"
  },
  "conflictingLog": {
    "id": "string",
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z"
  }
}