Create User Assignments

This endpoint adds direct project and task assignments to a user. Existing assignments are kept.

Endpoint

POST /v1/user-assignments/user-assignments

Authentication

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

Required Scope

user-assignments:write

Request Body

Field	Type	Required	Description
userId	string	Yes	User who receives the assignments.
projectAssignments	string[]	Yes	Project IDs to assign. Send [] if you are only adding tasks. If it is missing, the API returns 500.
taskAssignments	{ projectId: string; taskId: string }[]	Yes	Tasks to assign. Send [] if you are only adding projects. If it is missing, the API returns 500.

At least one of projectAssignments or taskAssignments must contain an item.

Example Request Body

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

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/user-assignments/user-assignments" \
  -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",
  {
    method: "POST",
    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

POST /v1/user-assignments/user-assignments 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 201 Created.

Example Response

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

Behavior

• The operation adds assignments. It does not remove the user’s existing assignments. To replace them, use Update User Assignments.
• For each project you assign, Crewsum also assigns that project’s default task when the task is active.
• Each task’s projectId must be a project the user already has as a direct assignment or a project in projectAssignments. Projects the user receives only through a user group do not count. Otherwise, the API returns 500.
• Assigning a project or task the user already has directly returns 500. Send only new assignments.
• The request is not all-or-nothing. Crewsum saves the project assignments first and the task assignments second. If the task step fails, the project assignments are kept.
• Every project in projectAssignments must exist in your account, and every task must exist under the projectId you send with it. Otherwise, the API returns 400 and nothing is saved.
• The user must exist. Otherwise, the API returns 500.
• The response echoes userId exactly as you sent it.

Error Responses

Status	Meaning
400	"At least one assignment must be supplied": both arrays were empty.
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. Nothing is saved.
500	"Error creating user assignments for <userId>": the request failed, for example because of a duplicate assignment, an unknown user, or a task whose project is not assigned to the user.
500	A missing projectAssignments or taskAssignments 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.