Update User Assignments

This endpoint replaces all of a user’s direct project and task assignments with the ones you send.

Endpoint

PUT /v1/user-assignments/user-assignments/:id

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

user-assignments:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	User whose assignments are replaced.

Request Body

Field	Type	Required	Description
userId	string	No	If you send it, it must match the route id.
projectAssignments	string[]	Yes	The complete set of direct project assignments. Send [] for none. If it is missing, the API returns 500.
taskAssignments	{ projectId: string; taskId: string }[]	Yes	The complete set of direct task assignments. Send [] for none. If it is missing, the API returns 500.

Example Request Body

{
  "userId": "user-a",
  "projectAssignments": ["project-mno123pqr4567890"],
  "taskAssignments": [
    {
      "projectId": "project-mno123pqr4567890",
      "taskId": "task-pqr123stu4567890"
    }
  ]
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/user-assignments/user-assignments/user-a" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-a",
    "projectAssignments": ["project-mno123pqr4567890"],
    "taskAssignments": [
      {
        "projectId": "project-mno123pqr4567890",
        "taskId": "task-pqr123stu4567890"
      }
    ]
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/user-assignments/user-assignments/user-a",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: "user-a",
      projectAssignments: ["project-mno123pqr4567890"],
      taskAssignments: [
        {
          projectId: "project-mno123pqr4567890",
          taskId: "task-pqr123stu4567890",
        },
      ],
    }),
  },
);
const result = await response.json();

HTTP

PUT /v1/user-assignments/user-assignments/user-a HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "userId": "user-a",
  "projectAssignments": ["project-mno123pqr4567890"],
  "taskAssignments": [
    {
      "projectId": "project-mno123pqr4567890",
      "taskId": "task-pqr123stu4567890"
    }
  ]
}

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully updated user assignments for user-a",
  "data": {
    "userId": "user-a"
  }
}

Behavior

• Crewsum removes all of the user’s direct project and task assignments, then adds the ones you send. Send both arrays as [] to remove every direct assignment.
• Assignments the user receives through user groups are not changed.
• Default tasks are not added. Only the tasks you send are assigned.
• Before removing anything, Crewsum checks that every project in projectAssignments exists in your account and that every task exists under the projectId you send with it. If a check fails, the API returns 400 and the user’s existing assignments are not changed.
• Each task’s projectId must also be in projectAssignments. Otherwise, the API returns 500. This check runs after the old assignments are removed.
• The request is not all-or-nothing. If adding the new assignments fails after the checks pass, the old ones are already removed, and the user can be left with no direct assignments.

Error Responses

Status	Meaning
400	"UserID missing": the ID path segment was empty.
400	"userId in request body must match the route id": userId in the body is different from the route id.
400	"Project or task not found for assignment": a project does not exist in your account, or a task does not exist under the projectId sent with it. Existing assignments are not changed.
500	"Error updating user assignments for <userId>": the request failed, for example because of an unknown user, a task whose project is not in projectAssignments, or a missing array.
500	A request with no body returns Fastify’s default error body: { "statusCode": 500, "error": "Internal Server Error", "message": "..." }.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.