---
title: "Invite and onboard a new user"
method: POST
path: "/public/v1/users"
tags: ["Users"]
---

# Invite and onboard a new user

`POST /public/v1/users`

### Overview
Onboard a new member to your organization. This action triggers an automated invitation email.

### Use Cases
- **New Employee**: Onboard a new team member with their required access level.
- **External Partner**: Invite a stakeholder to collaborate with specific roles.
- **Automation**: Programmatically create users as part of your internal onboarding flow.

### Invitation Lifecycle
1. **Request**: You provide the user's email and initial configuration.
2. **Created**: The user account is initialized with `confirmed: false`.
3. **Activation**: The user receives an email to set their password and log in.
4. **Completion**: Once logged in, the user's status changes to `confirmed: true`.

### Workflow Tip
- Use the `Location` header in the response to immediately access the new user's resource URI.
- You can pre-assign **teams** and **roles** during the invitation to ensure the user has access from their first login.

### Related Operations
- **List Users**: [GET /public/v1/users](#operations-Users-get)
- **Discover Roles**: [GET /public/v1/users/roles/available](#operations-Users_-_Roles-getAvailableRoles)
- **Assign Roles**: [POST /public/v1/users/{userId}/roles](#operations-Users_-_Roles-add)

### Required Permission
`manage_public_users`

## Request body

- PublicCreateUserRequest
  - `email` string, email, required
  - `firstname` string, nullable
  - `lastname` string, nullable
  - `teamIds` integer[], nullable
  - `roleNames` string[], nullable
  - `planId` integer, nullable

## Response `201`

Created - Invitation sent successfully. See Location header.

- PublicUserResponse
  - `id` integer, required
  - `active` boolean, required
  - `confirmed` boolean, required
  - `firstname` string, nullable
  - `lastname` string, nullable
  - `email` string, nullable
  - `customer` PublicUserResponseCustomerDTO, required
    - `id` integer, required
    - `name` string, required
  - `organization` PublicUserResponseOrganizationDTO
    - `id` integer, required
    - `name` string, required
  - `plan` PublicUserResponsePlanDTO
    - `id` integer, required
    - `name` string, required
    - `validFrom` string, date-time, nullable
  - `teams` PublicUserResponseTeamDTO[], required
    - `id` integer, required
    - `name` string, required
  - `roles` PublicUserRoleDTO[], required
    - `id` integer, required
    - `name` string, required
    - `description` string, nullable

## Other responses

- `400` — Bad Request - Validation error (e.g., invalid email format).
- `403` — 403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.
- `429` — 429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.
- `500` — 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.

---

[API](https://skmtc.net/prewave/apis/public-prewave-api.md) · [All operations](https://skmtc.net/prewave/apis/public-prewave-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prewave/public-prewave-api/revisions/466169815b78/schema)