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

# Custom fields

> Complete guide to custom fields in the Thena platform

Custom fields allow you to extend the standard ticket, account, and custom object information with additional data specific to your business needs. This guide explains how custom fields work and how to use them effectively.

These fields provide flexibility to capture and manage specialized information beyond standard fields. They can be added to tickets, accounts and custom objects, enabling you to:

* Collect specific business information
* Standardize data collection
* Enable advanced reporting
* Automate workflows based on field values

## Field sources

Custom fields can be associated with different sources:

<CardGroup cols={3}>
  <Card title="Ticket fields">
    Fields that appear on tickets for tracking specific ticket-related information
  </Card>

  <Card title="Account fields">
    Fields that store account-specific information and appear on account records
  </Card>

  <Card title="Custom object fields">
    Fields that extend custom objects with additional attributes and data points
  </Card>
</CardGroup>

## Field configuration

Each custom field can be configured with various properties:

<AccordionGroup>
  <Accordion title="Basic properties">
    Essential properties for every custom field:

    * **Name**: Unique identifier for the field
    * **Display name**: Label shown to users
    * **Description**: Help text explaining the field's purpose
    * **Field type**: Data type for the field
    * **Source type**: Ticket, Account, or Custom Object
    * **Default value**: Initial value when creating records
  </Accordion>

  <Accordion title="Team settings">
    Team-specific configurations:

    * **Team association**: Link field to specific teams
    * **Auto-add to forms**: Automatically add to new forms
    * **Field permissions**: Control who can view/edit
    * **Source visibility**: Control visibility per source type
  </Accordion>

  <Accordion title="Display options">
    Control how the field appears:

    * **Placeholder text**: Example text shown when empty
    * **Hint text**: Helper text below the field
    * **Field width**: Display width in forms
    * **Field order**: Position in form layout
    * **Source-specific display**: Different display per source type
  </Accordion>

  <Accordion title="Visibility rules">
    Control field visibility:

    * **Visible to customer**: Show in customer portal
    * **Editable by customer**: Allow customer edits
    * **Conditional display**: Show based on conditions
    * **Role-based visibility**: Show for specific roles
    * **Source-based rules**: Different rules per source
  </Accordion>
</AccordionGroup>

## Field types

The Thena platform supports a wide range of field types to capture different kinds of data. Each type has specific properties and validation rules.

### Text fields

<AccordionGroup>
  <Accordion title="Single line text">
    Basic text input for short responses.

    * **Use for**: Names, titles, references
    * **Max length**: 255 characters
    * **Validation**: Optional character limit
    * **Common uses**:
      * Ticket: Reference numbers, short descriptions
      * Account: Company aliases, industry codes
      * Custom Object: Identifiers, short attributes
  </Accordion>

  <Accordion title="Multi line text">
    Text area for longer responses.

    * **Use for**: Descriptions, notes, comments
    * **Max length**: 65,535 characters
    * **Validation**: Optional character limit
    * **Common uses**:
      * Ticket: Detailed descriptions, internal notes
      * Account: Company descriptions, special instructions
      * Custom Object: Detailed attributes, documentation
  </Accordion>

  <Accordion title="Rich text">
    Formatted text with styling options.

    * **Use for**: Detailed descriptions, formatted content
    * **Features**: Formatting, lists, links
    * **Storage**: HTML content
    * **Common uses**:
      * Ticket: Solution descriptions, formatted responses
      * Account: Formatted company profiles
      * Custom Object: Rich content storage
  </Accordion>
</AccordionGroup>

### Numeric fields

<AccordionGroup>
  <Accordion title="Integer">
    Whole number values.

    * **Use for**: Counts, quantities, whole numbers
    * **Range**: -2,147,483,648 to 2,147,483,647
    * **Validation**: Optional min/max values
  </Accordion>

  <Accordion title="Decimal">
    Numbers with decimal points.

    * **Use for**: Measurements, percentages
    * **Precision**: Up to 10 decimal places
    * **Validation**: Optional decimal places limit
  </Accordion>

  <Accordion title="Currency">
    Monetary values with currency support.

    * **Use for**: Prices, costs, budgets
    * **Features**: Currency symbol, formatting
    * **Validation**: Currency-specific rules
  </Accordion>
</AccordionGroup>

### Date and time fields

<AccordionGroup>
  <Accordion title="Date">
    Calendar date selection.

    * **Use for**: Deadlines, schedules
    * **Format**: YYYY-MM-DD
    * **Features**: Date picker
  </Accordion>

  <Accordion title="Date and time">
    Combined date and time selection.

    * **Use for**: Scheduled events, timestamps
    * **Format**: YYYY-MM-DD HH:mm:ss
    * **Features**: Date and time picker
  </Accordion>

  <Accordion title="Time">
    Time selection only.

    * **Use for**: Duration, time slots
    * **Format**: HH:mm:ss
    * **Features**: Time picker
  </Accordion>
</AccordionGroup>

### Choice fields

<AccordionGroup>
  <Accordion title="Single choice">
    Select one option from a list.

    * **Use for**: Categories, status values
    * **Features**: Dropdown or list
    * **Options**: Customizable choices
  </Accordion>

  <Accordion title="Multi choice">
    Select multiple options from a list.

    * **Use for**: Tags, multiple categories
    * **Features**: Multi-select dropdown
    * **Options**: Customizable choices
  </Accordion>

  <Accordion title="Radio buttons">
    Visual single choice selection.

    * **Use for**: Clear option choices
    * **Features**: Visual radio buttons
    * **Best for**: 2-5 options
  </Accordion>

  <Accordion title="Checkboxes">
    Visual multiple choice selection.

    * **Use for**: Multiple selections
    * **Features**: Visual checkboxes
    * **Best for**: 2-10 options
  </Accordion>
</AccordionGroup>

### Specialized fields

<AccordionGroup>
  <Accordion title="Email">
    Email address input with validation.

    * **Use for**: Contact information
    * **Validation**: Email format
    * **Features**: Email verification
  </Accordion>

  <Accordion title="Phone number">
    Phone number input with formatting.

    * **Use for**: Contact information
    * **Validation**: Phone format
    * **Features**: International format support
  </Accordion>

  <Accordion title="URL">
    Web address input with validation.

    * **Use for**: Website links
    * **Validation**: URL format
    * **Features**: Link verification
  </Accordion>

  <Accordion title="IP address">
    IP address input with validation.

    * **Use for**: Network information
    * **Validation**: IPv4/IPv6 format
    * **Features**: IP format verification
  </Accordion>

  <Accordion title="Password">
    Secure password input field.

    * **Use for**: Sensitive information
    * **Features**: Masked input
    * **Security**: Encrypted storage
  </Accordion>
</AccordionGroup>

### Advanced fields

<AccordionGroup>
  <Accordion title="Calculated">
    Computed values based on other fields.

    * **Use for**: Formulas, computations
    * **Features**: Dynamic calculation
    * **Dependencies**: Based on other fields
    * **Common uses**:
      * Ticket: SLA calculations, time tracking
      * Account: Revenue calculations, usage metrics
      * Custom Object: Computed attributes
  </Accordion>

  <Accordion title="Lookup">
    Reference values from other records.

    * **Use for**: Related data
    * **Features**: Cross-source relationships
    * **Options**: Filtered lookups
    * **Common uses**:
      * Ticket: Related accounts, parent tickets
      * Account: Related contacts, parent accounts
      * Custom Object: Related records
  </Accordion>

  <Accordion title="Toggle/boolean">
    True/false or on/off values.

    * **Use for**: Simple flags
    * **Features**: Visual toggle
    * **Values**: True/false
    * **Common uses**:
      * Ticket: Feature flags, approval status
      * Account: Active status, premium features
      * Custom Object: State indicators
  </Accordion>
</AccordionGroup>

## Validation

Field validation ensures data quality and consistency across tickets, accounts, and custom objects.

### Validation types

<AccordionGroup>
  <Accordion title="Required field validation">
    Control when fields must have values:

    * **Required on creation**: Must be filled when creating
    * **Required on closure**: Must be filled before closing
    * **Conditionally required**: Required based on conditions
    * **Role-based requirements**: Required for specific roles
    * **Source-specific requirements**: Different rules per source type
  </Accordion>

  <Accordion title="Format validation">
    Ensure correct data format:

    * **Text format**: Length, pattern matching
    * **Number format**: Range, decimals
    * **Date format**: Range, valid dates
    * **Email format**: Valid email structure
    * **Source-specific formats**: Format rules per source
  </Accordion>

  <Accordion title="Value validation">
    Validate field values:

    * **Range checks**: Min/max values
    * **List validation**: Valid option selection
    * **Unique values**: No duplicates allowed
    * **Dependencies**: Based on other fields
    * **Cross-source validation**: Validate across sources
  </Accordion>
</AccordionGroup>

### Advanced validation

<AccordionGroup>
  <Accordion title="Custom validation">
    Build custom validation rules:

    * **Custom functions**: JavaScript validation
    * **Complex rules**: Multi-field validation
    * **API validation**: External validation
    * **Async validation**: Background checks
    * **Cross-source rules**: Validate across sources
  </Accordion>

  <Accordion title="Conditional validation">
    Context-based validation:

    * **Field dependencies**: Based on other fields
    * **Status rules**: Based on status
    * **Role rules**: Based on user role
    * **Team rules**: Based on team
    * **Source rules**: Based on source type
  </Accordion>

  <Accordion title="Cross-field validation">
    Validate multiple fields:

    * **Field comparison**: Compare values
    * **Field groups**: Group validation
    * **Calculated fields**: Formula validation
    * **Related fields**: Relationship rules
    * **Cross-source fields**: Validate across sources
  </Accordion>
</AccordionGroup>

### Error handling

<AccordionGroup>
  <Accordion title="Error messages">
    Configure validation messages:

    * **Custom messages**: Field-specific errors
    * **Localization**: Multi-language support
    * **Dynamic text**: Context-based messages
    * **Help text**: User guidance
    * **Source-specific messages**: Different messages per source
  </Accordion>

  <Accordion title="Error display">
    Control error presentation:

    * **Inline errors**: Show next to field
    * **Summary errors**: Group all errors
    * **Error styling**: Visual presentation
    * **Error timing**: When to show errors
    * **Source-specific display**: Different display per source
  </Accordion>

  <Accordion title="Error actions">
    Handle validation failures:

    * **Block submission**: Prevent saving
    * **Warning only**: Allow with warning
    * **Auto-correction**: Fix common errors
    * **Suggestions**: Provide valid options
    * **Source-specific actions**: Different actions per source
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Field design">
    • Use clear, descriptive names <br />
    • Choose appropriate field types <br />
    • Set helpful default values <br />
    • Add descriptive hints <br />
    • Consider source-specific needs <br />
  </Card>

  <Card title="Field management">
    • Review field usage regularly <br />
    • Archive unused fields <br />
    • Document field purposes <br />
    • Maintain consistent naming <br />
    • Monitor cross-source relationships <br />
  </Card>

  <Card title="Validation design">
    • Keep rules simple and clear <br />
    • Provide helpful error messages <br />
    • Use appropriate validation types <br />
    • Test edge cases <br />
    • Consider source-specific needs <br />
  </Card>

  <Card title="Error handling">
    • Show errors immediately <br />
    • Provide clear guidance <br />
    • Offer error resolution <br />
    • Log validation issues <br />
    • Handle cross-source validation <br />
  </Card>
</CardGroup>

## API reference

### Create custom field

```json theme={null}
{
  "name": "device_type",
  "displayName": "Device Type",
  "description": "Type of device the customer is using",
  "type": "SELECT",
  "isRequired": false,
  "isActive": true,
  "options": [
    {
      "label": "Mobile",
      "value": "mobile"
    },
    {
      "label": "Desktop",
      "value": "desktop"
    },
    {
      "label": "Tablet",
      "value": "tablet"
    }
  ],
  "defaultValue": "desktop",
  "validation": {
    "pattern": null,
    "min": null,
    "max": null
  }
}
```

### Available operations

<Accordion title="Custom field management" icon="input-text">
  ```bash theme={null}
  # Create a custom field
  POST /v1/custom-field
  Content-Type: application/json

  # Get all custom fields
  GET /v1/custom-field

  # Update custom fields
  PATCH /v1/custom-field
  Content-Type: application/json

  # Get custom fields by IDs
  GET /v1/custom-field/fetchByIds

  # Search custom field by name
  GET /v1/custom-field/search

  # Delete custom fields
  POST /v1/custom-field/delete
  Content-Type: application/json

  # Get all custom field types
  GET /v1/custom-field/types
  ```

  <Note>
    All endpoints require authentication with Bearer token, API key, and Organization ID in the headers.
  </Note>

  For detailed API specifications, see <a href="/api-reference/platform/custom-fields" target="_blank">Custom Fields API Reference</a>
</Accordion>

<Note>
  The structure and available options for custom fields depend on the field type selected. The example above shows a SELECT type field with predefined options.
</Note>

Each field type has its own specific configuration options and validation rules.