> ## 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.

# Create Input Variable

> Create a new User Defined input variable in the workspace's registry. The variable key must be unique across the workspace's own variables and the global System variables.

Use this endpoint to **create a new User Defined input variable** in the workspace's registry.

## Endpoint

**POST** `/input-variable/create`

**Content-Type:** `application/json`
**Authentication:** Required (workspace auth)

## Request Body

```json theme={null}
{
  "variable_key": "customer_plan",
  "type": "string",
  "description": "Subscription plan name"
}
```

| Field          | Type   | Required | Description                                                                                                                         |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `variable_key` | string | Yes      | Unique key for the variable. Letters, numbers and underscore only, and must start with a letter or underscore.                      |
| `type`         | string | Yes      | Data type of the variable. One of: `string`, `number`, `date`, `email`, `phone`, `name`, `amount`, `address`, `pincode`, `no_type`. |
| `description`  | string | No       | Human-readable description of the variable.                                                                                         |

## Response

```json theme={null}
{
  "message": "Input variable added successfully",
  "data": {
    "id": 57,
    "variable_key": "customer_plan",
    "type": "string"
  }
}
```

## Behavior

* The new variable is always created as **User Defined** (`IS_SYSTEM = 0`) and active (`STATUS = 1`).
* `variable_key` must be unique across **both** the workspace's own variables and the global System variables — a key already used by either is rejected.
* `type` is normalized to lowercase and validated against the allowed list before saving.

## Error Cases

| Error                                                                                                       | Cause                                                                      |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Variable Key may contain only letters, numbers and underscore, and must start with a letter or underscore` | `variable_key` fails the token format check                                |
| `Type must be one of: string, number, date, email, phone, name, amount, address, pincode, no_type`          | `type` is not one of the allowed values                                    |
| `This variable <variable_key> already exists as a system variable`                                          | `variable_key` matches an existing System variable                         |
| `This variable <variable_key> already exists in this workspace`                                             | `variable_key` matches an existing User Defined variable in this workspace |

## Example cURL

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/input-variable/create \
  -H "Content-Type: application/json" \
  -H "token: <api_key>" \
  -d '{
    "variable_key": "customer_plan",
    "type": "string",
    "description": "Subscription plan name"
  }'
```


## OpenAPI

````yaml api-reference/openapi.json POST /input-variable/create
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:
  /input-variable/create:
    post:
      tags:
        - Input Variables
      summary: Create input variable
      description: >-
        Create a new User Defined input variable in the workspace's registry.
        The variable key must be unique across the workspace's own variables and
        the global System variables.
      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:
                - variable_key
                - type
              properties:
                variable_key:
                  type: string
                  description: >-
                    Unique key for the variable. Letters, numbers and underscore
                    only, and must start with a letter or underscore.
                type:
                  type: string
                  enum:
                    - string
                    - number
                    - date
                    - email
                    - phone
                    - name
                    - amount
                    - address
                    - pincode
                    - no_type
                  description: Data type of the variable
                description:
                  type: string
                  description: Human-readable description of the variable
      responses:
        '200':
          description: Input variable created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      variable_key:
                        type: string
                      type:
                        type: string
        '400':
          description: >-
            Bad Request - invalid variable_key format, invalid type, or
            variable_key already exists
        '401':
          description: Unauthorized
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````