Create User

This endpoint creates a user, creates their sign-in profile, and sends them an invitation email.

Endpoint

POST /v1/users/users

Authentication

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

Required Scope

users:write

Request Body

Field	Type	Required	Description
username	string	Yes	The user ID. Crewsum stores it in lowercase. If it is missing or empty, the API returns 400.
name	string	Yes	Display name. If it is missing, the API returns 500.
role	"tenant-admin" | "admin" | "assoc" | "emp" | "no-role"	Yes	User role. See the role list below. If it is missing, the API returns 500.
email	string	Yes	Email address. The invitation email goes to this address. If it is missing, the API returns 500.
disabled	boolean	No	Ignored. It has no effect.
startDate	string | null	No	Start date in YYYY-MM-DD format.
endDate	string | null	No	End date in YYYY-MM-DD format.
customFields	Record<string, string>	No	Custom field values. Defaults to {}.
assignments	object	No	Initial direct project and task assignments. See assignments.
suppliers	object	No	Supplier for the user. See suppliers.
groupIds	string[]	No	User groups to add the user to. Every ID must exist, or the API returns 400.

The server does not check the format of email, startDate, endDate, or role. Send values in the documented formats.

Roles:

• tenant-admin: administrator who can also manage billing.
• admin: administrator.
• assoc: associate.
• emp: employee.
• no-role: no role assigned.

assignments object

Field	Type	Required	Description
projectAssignments	string[]	Yes	Project IDs to assign. Send [] if there are none.
taskAssignments	{ projectId: string; taskId: string }[]	Yes	Tasks to assign. Each projectId must also be in projectAssignments. Send [] if none.

suppliers object

Field	Type	Required	Description
supplierId	string	Yes	Supplier ID.
supplierContactIds	string[]	No	Supplier contacts to link to the user. If you send no contact IDs, profile.supplier stays null on Get User.

Example Request Body

{
  "username": "user-a",
  "name": "User Display Name",
  "role": "assoc",
  "email": "placeholder@example.com",
  "startDate": "2023-01-01",
  "customFields": {
    "department": "Operations"
  },
  "groupIds": ["36b735f8-4dd7-4c3c-836f-35d2fe84e872"],
  "assignments": {
    "projectAssignments": ["project-mno123pqr4567890"],
    "taskAssignments": [
      {
        "projectId": "project-mno123pqr4567890",
        "taskId": "task-pqr123stu4567890"
      }
    ]
  }
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/users/users" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user-a",
    "name": "User Display Name",
    "role": "assoc",
    "email": "placeholder@example.com",
    "startDate": "2023-01-01",
    "customFields": {
      "department": "Operations"
    },
    "groupIds": ["36b735f8-4dd7-4c3c-836f-35d2fe84e872"],
    "assignments": {
      "projectAssignments": ["project-mno123pqr4567890"],
      "taskAssignments": [
        {
          "projectId": "project-mno123pqr4567890",
          "taskId": "task-pqr123stu4567890"
        }
      ]
    }
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/users/users", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    username: "user-a",
    name: "User Display Name",
    role: "assoc",
    email: "placeholder@example.com",
    startDate: "2023-01-01",
    customFields: {
      department: "Operations",
    },
    groupIds: ["36b735f8-4dd7-4c3c-836f-35d2fe84e872"],
    assignments: {
      projectAssignments: ["project-mno123pqr4567890"],
      taskAssignments: [
        {
          projectId: "project-mno123pqr4567890",
          taskId: "task-pqr123stu4567890",
        },
      ],
    },
  }),
});
const result = await response.json();

HTTP

POST /v1/users/users HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "username": "user-a",
  "name": "User Display Name",
  "role": "assoc",
  "email": "placeholder@example.com",
  "startDate": "2023-01-01",
  "customFields": {
    "department": "Operations"
  },
  "groupIds": ["36b735f8-4dd7-4c3c-836f-35d2fe84e872"],
  "assignments": {
    "projectAssignments": ["project-mno123pqr4567890"],
    "taskAssignments": [
      {
        "projectId": "project-mno123pqr4567890",
        "taskId": "task-pqr123stu4567890"
      }
    ]
  }
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "User Successfully Created",
  "data": {
    "code": "eyJ0ZW5hbnRJZCI6InRlbmFudC0xMjMiLCJ1c2VySWQiOiJ1c2VyLWEiLCJwYXNzd29yZCI6IkV4YW1wbGUtVGVtcC1QYXNzMSEifQ=="
  }
}

Treat the code as a secret

data.code is the new user’s auto-login code. It is a base64-encoded JSON object that contains the tenant ID, the user ID, and the user’s temporary password in plain text. Anyone who has this code can sign in as the new user. The Crewsum app accepts it at /auth?authCode=<code>. Do not log it, store it, or show it to anyone other than the new user.

Behavior

• Crewsum stores the user ID in lowercase, as <tenantId>#<username>. Use the username you sent as the user ID in other endpoints.
• Crewsum creates a sign-in profile for the user with a temporary password.
• Crewsum always sends an invitation email to email. The email contains a sign-in link and the temporary password. If the email cannot be sent, the user is still created and the API still returns 201.
• Projects and tasks that are set to auto-assign in your account are added to the user, in addition to the projects and tasks in assignments.
• For each project you assign, Crewsum also assigns that project’s default task when the task is active.
• If you send groupIds, the user is added to those groups and receives the groups’ project and task assignments.
• Crewsum updates the number of paid seats on your subscription. This can change your bill.
• Creating the user record, the sign-in profile, assignments, supplier contacts, and group memberships is all-or-nothing. If one of these steps fails, Crewsum removes the user record and the sign-in profile.
• After the user is created, Crewsum sends the users.created webhook event.

Error Responses

Status	Meaning
400	"User ID not found": username is missing or empty.
400	"Username already exists": a user with this username already exists.
400	"Email is already associated with another account": the email address is already in use by another sign-in profile.
400	"Username already exists in authentication; contact an administrator to recover the account": a sign-in profile already exists for this ID.
400	"One or more user groups were not found": an ID in groupIds does not exist.
400	"Project or task not found for assignment": a project in assignments does not exist in your account, or a task does not exist under the projectId sent with it.
500	"Error creating user": any other failure, including a missing name, email, or role, an unknown supplier, or a task whose project is not in projectAssignments.

Authentication and scope failures are described in Errors.

Related Webhooks

users.created View webhook event details.