> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard User

> Onboard a new user/customer into the portal. Creates a complete account setup including registration, company, user, and workspace in a single API call.

Use this endpoint to **onboard a new user/customer** into the portal. This creates a complete account setup including registration, company, user, and workspace in a single API call.

## Endpoint

**POST** `/users/onboard`

**Content-Type:** `application/json`
**Authentication:** Required (API token)

## Request Body

```json theme={null}
{
  "email_id": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Corp"
}
```

### Parameters

| Parameter      | Type   | Required | Description                                                   |
| -------------- | ------ | -------- | ------------------------------------------------------------- |
| `email_id`     | string | Yes      | Email address of the user to onboard. Also accepts `email`.   |
| `first_name`   | string | Yes      | First name of the user. Also accepts `firstName`.             |
| `last_name`    | string | Yes      | Last name of the user. Also accepts `lastName`.               |
| `company_name` | string | Yes      | Company name for the new account. Also accepts `companyName`. |

### Notes

* All four fields are **required**.
* The `email_id` must not already be registered in the system.
* The `company_name` must be **unique** — it cannot match an existing company.
* The email domain is validated against restricted domains. If the domain is restricted, the request will be rejected.
* A unique 12-digit `customer_salt` is auto-generated and returned in the response. This can be used later to generate API tokens via the [Get Token by Customer ID](/api-reference/users/get-token-by-customerid) endpoint.
* The onboarded user is created as an **Admin** with a default workspace and **20 free minutes**.

## Success Response

```json theme={null}
{
  "message": "User onboarded successfully",
  "data": {
    "registration_id": 101,
    "user_id": 55,
    "company_id": 12,
    "workspace_id": 8,
    "customer_salt": "048372910564"
  }
}
```

### Response Fields

| Field             | Type   | Description                                                           |
| ----------------- | ------ | --------------------------------------------------------------------- |
| `registration_id` | number | ID of the registration record created.                                |
| `user_id`         | number | ID of the newly created user.                                         |
| `company_id`      | number | ID of the newly created company.                                      |
| `workspace_id`    | number | ID of the default workspace created for the user.                     |
| `customer_salt`   | string | Unique 12-digit customer identifier. Use this to generate API tokens. |

## Error Responses

| Error                               | Description                                      |
| ----------------------------------- | ------------------------------------------------ |
| `EMAIL_ALREADY_REGISTERED`          | The email is already associated with an account. |
| `WORKFLOW_NAME_ALREADY_REGISTERED`  | The company name is already taken.               |
| `COMPANY_DOMAIN_ALREADY_REGISTERED` | The email domain is already registered.          |

## Example cURL

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/users/onboard \
  -H "Content-Type: application/json" \
  -H "Authorization: <api_key>" \
  -d '{
    "email_id": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Acme Corp"
  }'
```


## OpenAPI

````yaml api-reference/openapi.json POST /users/onboard
openapi: 3.1.0
info:
  title: >-
    UnleashX - Build human like conversations | Voice Agents | Automations | AI
    Workforce
  version: 1.0.0
  description: UnleashX - Your home for human like conversations
servers:
  - url: https://www.tryunleashx.com/api/v1/global/
security:
  - bearerAuth: []
paths:
  /users/onboard:
    post:
      tags:
        - Users
      summary: Onboard user
      description: >-
        Onboard a new user/customer into the portal. Creates a complete account
        setup including registration, company, user, and workspace in a single
        API call.
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email_id
                - first_name
                - last_name
                - company_name
              properties:
                email_id:
                  type: string
                  format: email
                  description: Email address of the user to onboard. Also accepts 'email'.
                first_name:
                  type: string
                  description: First name of the user. Also accepts 'firstName'.
                last_name:
                  type: string
                  description: Last name of the user. Also accepts 'lastName'.
                company_name:
                  type: string
                  description: >-
                    Company name for the new account. Must be unique. Also
                    accepts 'companyName'.
      responses:
        '200':
          description: User onboarded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      registration_id:
                        type: integer
                        description: ID of the registration record created
                      user_id:
                        type: integer
                        description: ID of the newly created user
                      company_id:
                        type: integer
                        description: ID of the newly created company
                      workspace_id:
                        type: integer
                        description: ID of the default workspace created for the user
                      customer_salt:
                        type: string
                        description: >-
                          Unique 12-digit customer identifier. Use this to
                          generate API tokens via the
                          /users/gettokenbycustomerid endpoint.
        '400':
          description: >-
            Bad Request - EMAIL_ALREADY_REGISTERED,
            WORKFLOW_NAME_ALREADY_REGISTERED, or
            COMPANY_DOMAIN_ALREADY_REGISTERED
        '401':
          description: Unauthorized
        '422':
          description: Validation error - missing required fields
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````