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

# Field Types

> All available field types for form_fill steps including semantic fields with automatic validation

Custom fields are used in `form_fill` steps to collect structured data from users. Fields can be simple inputs or **semantic fields** that integrate with automation rules for automatic validation.

## Field Categories

<CardGroup cols={2}>
  <Card title="Basic Fields" icon="input-text">
    Standard inputs: text, number, date, boolean, select, file
  </Card>

  <Card title="Contact Fields" icon="address-book">
    Email, phone, URL with validation options
  </Card>

  <Card title="Semantic Fields" icon="brain">
    Country, name, wallet, domain with automatic rule integration
  </Card>

  <Card title="Complex Fields" icon="layer-group">
    Address, entity arrays, sub-merchants, nested objects
  </Card>
</CardGroup>

## Common Field Properties

All field types share these base properties:

| Property            | Type    | Required | Description                                                            |
| ------------------- | ------- | -------- | ---------------------------------------------------------------------- |
| `field_id`          | string  | ✓        | Unique identifier for the field (auto-generated)                       |
| `name`              | string  | ✓        | Display name shown to user                                             |
| `type`              | string  | ✓        | Field type                                                             |
| `field_key`         | string  |          | **Portable key for webhooks** - use instead of `field_id` in your code |
| `required`          | boolean |          | Whether field is required (default: false)                             |
| `description`       | string  |          | Internal description                                                   |
| `tooltip`           | string  |          | Tooltip shown on hover                                                 |
| `instructions`      | string  |          | Instructions shown below field                                         |
| `placeholder`       | string  |          | Placeholder text in input                                              |
| `help_text`         | string  |          | Help text shown below field                                            |
| `default_value`     | any     |          | Default value for the field                                            |
| `validation_rules`  | object  |          | Custom validation rules                                                |
| `conditional_logic` | object  |          | Show/hide based on other field values                                  |

<Tip>
  **Use `field_key` for portable integrations**: The `field_id` is auto-generated and different between staging and production. Define a `field_key` (e.g., `full_name`, `date_of_birth`, `is_pep`) to get a consistent identifier in webhooks that works across all environments.
</Tip>

***

## Basic Fields

### Text Field

Simple text input.

```json theme={null}
{
  "field_id": "occupation",
  "name": "Occupation",
  "type": "text",
  "required": true,
  "max_length": 100,
  "placeholder": "Enter your occupation"
}
```

| Property     | Type    | Description              |
| ------------ | ------- | ------------------------ |
| `max_length` | integer | Maximum character length |

### Number Field

Numeric input with optional range validation.

```json theme={null}
{
  "field_id": "age",
  "name": "Age",
  "type": "number",
  "required": true,
  "min_value": 18,
  "max_value": 120
}
```

| Property    | Type   | Description           |
| ----------- | ------ | --------------------- |
| `min_value` | number | Minimum allowed value |
| `max_value` | number | Maximum allowed value |

### Date Field

Date picker with optional range constraints.

```json theme={null}
{
  "field_id": "date_of_birth",
  "name": "Date of Birth",
  "type": "date",
  "required": true,
  "max_date": "today"
}
```

| Property   | Type   | Description                          |
| ---------- | ------ | ------------------------------------ |
| `min_date` | string | Minimum date (ISO format or "today") |
| `max_date` | string | Maximum date (ISO format or "today") |

### Boolean Field

Checkbox/toggle input.

```json theme={null}
{
  "field_id": "terms_accepted",
  "name": "I accept the Terms and Conditions",
  "type": "boolean",
  "required": true
}
```

### Select Field

Dropdown selection with predefined options.

```json theme={null}
{
  "field_id": "employment_status",
  "name": "Employment Status",
  "type": "select",
  "required": true,
  "options": ["Employed", "Self-employed", "Unemployed", "Retired", "Student"],
  "allow_custom_option": false
}
```

| Property              | Type    | Description                      |
| --------------------- | ------- | -------------------------------- |
| `options`             | array   | List of available options        |
| `allow_custom_option` | boolean | Allow user to enter custom value |

### Multi-Select Field

Multiple selection dropdown.

```json theme={null}
{
  "field_id": "business_activities",
  "name": "Business Activities",
  "type": "multi_select",
  "required": true,
  "options": ["Import/Export", "E-commerce", "Financial Services", "Consulting", "Manufacturing"],
  "min_selections": 1,
  "max_selections": 5
}
```

| Property         | Type    | Description                 |
| ---------------- | ------- | --------------------------- |
| `options`        | array   | List of available options   |
| `min_selections` | integer | Minimum required selections |
| `max_selections` | integer | Maximum allowed selections  |

### File Field

File upload input.

```json theme={null}
{
  "field_id": "additional_document",
  "name": "Additional Document",
  "type": "file",
  "required": false,
  "allowed_mime_types": ["application/pdf", "image/jpeg", "image/png"]
}
```

| Property             | Type  | Description                |
| -------------------- | ----- | -------------------------- |
| `allowed_mime_types` | array | List of allowed MIME types |

***

## Contact Fields

### Email Field

Email input with optional verification.

```json theme={null}
{
  "field_id": "email",
  "name": "Email Address",
  "type": "email",
  "required": true,
  "validate_email": true,
  "block_disposable": true,
  "block_role_based": false
}
```

| Property           | Type    | Description                                   |
| ------------------ | ------- | --------------------------------------------- |
| `validate_email`   | boolean | Verify email exists via provider lookup       |
| `block_disposable` | boolean | Block disposable/temporary email domains      |
| `block_role_based` | boolean | Block role-based emails (info@, admin@, etc.) |

<Note>
  Email verification can be used with `EmailVerificationRule` in automation rules to auto-deny invalid emails or flag disposable domains.
</Note>

### Phone Field

Phone number input with validation options.

```json theme={null}
{
  "field_id": "phone",
  "name": "Phone Number",
  "type": "phone",
  "required": true,
  "format": "international",
  "validate_carrier": false,
  "block_voip": true,
  "block_disposable": true,
  "require_mobile": true
}
```

| Property           | Type    | Description                                         |
| ------------------ | ------- | --------------------------------------------------- |
| `format`           | string  | Expected format: `international`, `national`, `any` |
| `validate_carrier` | boolean | Validate carrier information via lookup             |
| `block_voip`       | boolean | Block VoIP/virtual phone numbers                    |
| `block_disposable` | boolean | Block disposable/temporary phone numbers            |
| `require_mobile`   | boolean | Require mobile phone (not landline)                 |

### URL Field

URL/website input.

```json theme={null}
{
  "field_id": "website",
  "name": "Company Website",
  "type": "url",
  "required": true,
  "auto_validate": false,
  "validation_profile": null
}
```

| Property             | Type    | Description                      |
| -------------------- | ------- | -------------------------------- |
| `auto_validate`      | boolean | Run web validation on this URL   |
| `validation_profile` | string  | Custom web validation profile ID |

***

## Semantic Fields

Semantic fields have special meaning and integrate with automation rules for automatic validation.

### Country Field

Country selection with semantic type for automation rules.

```json theme={null}
{
  "field_id": "nationality",
  "name": "Nationality",
  "type": "country",
  "country_type": "nationality",
  "required": true,
  "allowed_countries": null,
  "blocked_countries": ["KP", "IR", "SY"]
}
```

| Property            | Type   | Description                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `country_type`      | string | **Required.** Semantic type that determines which automation rules apply |
| `allowed_countries` | array  | List of allowed ISO 3166-1 alpha-2 country codes (frontend validation)   |
| `blocked_countries` | array  | List of blocked ISO 3166-1 alpha-2 country codes (frontend validation)   |

#### Country Types

| Type                 | Description                      | Use Case             |
| -------------------- | -------------------------------- | -------------------- |
| `nationality`        | Person's nationality/citizenship | Individual KYC       |
| `residence`          | Country of residence             | Individual KYC       |
| `incorporation`      | Country of incorporation         | Company KYC          |
| `tax_residence`      | Country of tax residence         | Tax compliance       |
| `birth_country`      | Country of birth                 | Individual KYC       |
| `business_operation` | Country where business operates  | Company/Merchant KYC |

<Tip>
  Country fields with a `country_type` will automatically trigger matching `CountryRule` automation rules. For example, if you have a rule for `nationality` from `KP`, it will only apply to fields with `country_type: "nationality"`.
</Tip>

### Name Field

Name input with automatic sanctions/adverse media validation.

```json theme={null}
{
  "field_id": "full_name",
  "name": "Full Legal Name",
  "type": "name",
  "name_type": "individual",
  "entity_role": null,
  "validate_lists": true,
  "validate_adverse_media": false,
  "required": true
}
```

| Property                 | Type    | Description                                                                                                                                                                                                       |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name_type`              | string  | Type of name: `individual`, `company`, `legal_name`                                                                                                                                                               |
| `entity_role`            | string  | Optional. Entity role for watchlist tagging: `individual`, `ubo`, `director`, `shareholder`, `representative`. When set, names extracted from this field are tagged with this role when auto-added to watchlists. |
| `validate_lists`         | boolean | Run this name against sanction lists (OFAC, UN, etc.)                                                                                                                                                             |
| `validate_adverse_media` | boolean | Run adverse media check on this name                                                                                                                                                                              |

<Warning>
  Enabling `validate_lists` or `validate_adverse_media` on name fields will trigger list checks during session processing and can trigger `ListMatchRule` automation rules.
</Warning>

<Tip>
  Use `entity_role` to automatically tag names for watchlist auto-add. For example, set `entity_role: "ubo"` on a name field for beneficial owners, and when the session is processed with `watchlist_auto_add` enabled, these names will be tagged as `ubo` in the watchlist.
</Tip>

### Wallet Field

Cryptocurrency wallet address input.

```json theme={null}
{
  "field_id": "eth_wallet",
  "name": "Ethereum Wallet Address",
  "type": "wallet",
  "blockchain": "ethereum",
  "validate_crypto": true,
  "required": false
}
```

| Property          | Type    | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| `blockchain`      | string  | Expected blockchain: `ethereum`, `bitcoin`, `any` |
| `validate_crypto` | boolean | Validate wallet against crypto sanction lists     |

### Document ID Field

Document identification number with format validation.

```json theme={null}
{
  "field_id": "tax_id",
  "name": "Tax ID Number",
  "type": "document_id",
  "id_type": "tax_id",
  "country": "US",
  "validate_format": true,
  "validate_checksum": true,
  "validate_against_lists": false,
  "required": true
}
```

| Property                 | Type    | Description                                                       |
| ------------------------ | ------- | ----------------------------------------------------------------- |
| `id_type`                | string  | Type: `passport`, `national_id`, `tax_id`, `company_reg`, `other` |
| `country`                | string  | ISO 3166-1 alpha-2 country code for format validation             |
| `validate_format`        | boolean | Validate ID format according to country/type rules                |
| `validate_checksum`      | boolean | Validate checksum if applicable (e.g., IBAN, tax IDs)             |
| `validate_against_lists` | boolean | Check if document ID appears in sanction/watchlists               |

### Domain Field

Domain/URL with optional web validation.

```json theme={null}
{
  "field_id": "business_domain",
  "name": "Business Website",
  "type": "domain",
  "auto_validate": true,
  "validation_profile": null,
  "required": true
}
```

| Property             | Type    | Description                                     |
| -------------------- | ------- | ----------------------------------------------- |
| `auto_validate`      | boolean | Automatically run web validation on this domain |
| `validation_profile` | string  | Web validation profile to use                   |

***

## Financial Fields

### Currency Field

Monetary amount input.

```json theme={null}
{
  "field_id": "monthly_revenue",
  "name": "Monthly Revenue",
  "type": "currency",
  "currency": "USD",
  "min_amount": 0,
  "max_amount": null,
  "amount_type": "monthly_volume",
  "apply_volume_rules": true,
  "required": true
}
```

| Property             | Type    | Description                                                                                        |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `currency`           | string  | Expected currency code (ISO 4217)                                                                  |
| `min_amount`         | number  | Minimum allowed amount                                                                             |
| `max_amount`         | number  | Maximum allowed amount                                                                             |
| `amount_type`        | string  | Semantic type: `transaction`, `monthly_volume`, `annual_revenue`, `capital`, `investment`, `other` |
| `apply_volume_rules` | boolean | Apply workflow `VolumeRule` to this field                                                          |

### Percentage Field

Percentage input (0-100).

```json theme={null}
{
  "field_id": "ownership_percentage",
  "name": "Ownership Percentage",
  "type": "percentage",
  "min_percentage": 0,
  "max_percentage": 100,
  "required": true
}
```

| Property         | Type   | Description        |
| ---------------- | ------ | ------------------ |
| `min_percentage` | number | Minimum percentage |
| `max_percentage` | number | Maximum percentage |

### Volume Field

Transaction volume input with automation rule support.

```json theme={null}
{
  "field_id": "expected_volume",
  "name": "Expected Monthly Volume",
  "type": "volume",
  "currency": "USD",
  "period": "monthly",
  "include_transaction_count": true,
  "volume_tiers": ["0-10K", "10K-100K", "100K-1M", "1M+"],
  "apply_volume_rules": true,
  "required": true
}
```

| Property                    | Type    | Description                               |
| --------------------------- | ------- | ----------------------------------------- |
| `currency`                  | string  | Currency for volume amount (default: USD) |
| `period`                    | string  | Period: `monthly`, `annual`               |
| `include_transaction_count` | boolean | Also capture expected transaction count   |
| `volume_tiers`              | array   | Predefined volume tiers for selection     |
| `apply_volume_rules`        | boolean | Apply workflow `VolumeRule` to this field |

<Note>
  Volume fields with `apply_volume_rules: true` will trigger matching `VolumeRule` automation rules during session processing.
</Note>

***

## Complex Fields

### Address Field

Complete address input with optional country-based automation.

```json theme={null}
{
  "field_id": "home_address",
  "name": "Home Address",
  "type": "address",
  "require_postal_code": true,
  "require_country": true,
  "capture_geolocation": false,
  "country_type": "residence",
  "required": true
}
```

| Property              | Type    | Description                                                                                                                    |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `require_postal_code` | boolean | Require postal/zip code                                                                                                        |
| `require_country`     | boolean | Require country selection (default: true)                                                                                      |
| `capture_geolocation` | boolean | Capture GPS coordinates                                                                                                        |
| `country_type`        | string  | If set, apply `CountryRule` to the country from this address. Options: `residence`, `business_operation`, `mailing`, `billing` |

### Entity Array Field

Array of related entities (directors, shareholders, beneficial owners).

```json theme={null}
{
  "field_id": "directors",
  "name": "Company Directors",
  "type": "entity_array",
  "entity_role": "director",
  "min_items": 1,
  "max_items": 10,
  "allow_company_entities": false,
  "max_recursion_depth": 1,
  "validate_lists": true,
  "validate_adverse_media": false,
  "required": true,
  "item_schema": {
    "full_name": {"type": "name", "required": true},
    "nationality": {"type": "country", "country_type": "nationality", "required": true},
    "date_of_birth": {"type": "date", "required": true},
    "ownership_percentage": {"type": "percentage", "required": false}
  }
}
```

| Property                 | Type    | Description                                                                     |
| ------------------------ | ------- | ------------------------------------------------------------------------------- |
| `entity_role`            | string  | Role: `director`, `shareholder`, `beneficial_owner`, `representative`, `custom` |
| `min_items`              | integer | Minimum number of entities required                                             |
| `max_items`              | integer | Maximum number of entities allowed                                              |
| `allow_company_entities` | boolean | Allow company entities (for multi-level UBO structures)                         |
| `max_recursion_depth`    | integer | Max depth for nested company structures                                         |
| `validate_lists`         | boolean | Run each entity name against sanction lists                                     |
| `validate_adverse_media` | boolean | Run adverse media on each entity                                                |
| `item_schema`            | object  | Schema for each entity item                                                     |

<Tip>
  Entity array fields support `ListMatchRule` with `entity_scope: "related_parties"` to apply different actions for list matches on directors/shareholders vs the primary subject.
</Tip>

### Sub-Merchant Field

Sub-merchant information for payment facilitator onboarding.

```json theme={null}
{
  "field_id": "sub_merchants",
  "name": "Sample Sub-Merchants",
  "type": "sub_merchant",
  "min_items": 1,
  "max_items": 10,
  "require_industry": true,
  "require_sample_url": true,
  "required": true
}
```

| Property             | Type    | Description                              |
| -------------------- | ------- | ---------------------------------------- |
| `min_items`          | integer | Minimum number of sub-merchants          |
| `max_items`          | integer | Maximum number of sub-merchants          |
| `require_industry`   | boolean | Require industry for each sub-merchant   |
| `require_sample_url` | boolean | Require sample URL for each sub-merchant |

### Array Field

Generic array input.

```json theme={null}
{
  "field_id": "previous_addresses",
  "name": "Previous Addresses (last 3 years)",
  "type": "array",
  "min_items": 0,
  "max_items": 5,
  "item_schema": {
    "type": "address"
  }
}
```

| Property      | Type    | Description             |
| ------------- | ------- | ----------------------- |
| `min_items`   | integer | Minimum number of items |
| `max_items`   | integer | Maximum number of items |
| `item_schema` | object  | Schema for array items  |

### Nested Object Field

Nested object with multiple sub-fields.

```json theme={null}
{
  "field_id": "source_of_funds",
  "name": "Source of Funds",
  "type": "nested_object",
  "required": true,
  "nested_fields": [
    {
      "field_id": "source_type",
      "name": "Source Type",
      "type": "select",
      "options": ["Employment", "Business", "Investments", "Inheritance", "Other"],
      "required": true
    },
    {
      "field_id": "description",
      "name": "Description",
      "type": "text",
      "required": true
    },
    {
      "field_id": "amount",
      "name": "Amount",
      "type": "currency",
      "currency": "USD"
    }
  ]
}
```

| Property        | Type  | Description                                      |
| --------------- | ----- | ------------------------------------------------ |
| `nested_fields` | array | Array of field definitions for the nested object |

***

## Conditional Logic

Fields can be shown/hidden based on other field values.

```json theme={null}
{
  "field_id": "pep_details",
  "name": "PEP Details",
  "type": "text",
  "required": true,
  "conditional_logic": {
    "show_when": {
      "field_id": "pep_status",
      "operator": "not_equals",
      "value": "No"
    }
  }
}
```

### Conditional Operators

| Operator       | Description                                |
| -------------- | ------------------------------------------ |
| `equals`       | Field value equals specified value         |
| `not_equals`   | Field value does not equal specified value |
| `in`           | Field value is in array of values          |
| `not_in`       | Field value is not in array of values      |
| `is_empty`     | Field is empty/null                        |
| `is_not_empty` | Field has a value                          |

***

## Field Types Reference

| Type            | Description             | Automation Integration             |
| --------------- | ----------------------- | ---------------------------------- |
| `text`          | Simple text input       | -                                  |
| `number`        | Numeric input           | -                                  |
| `date`          | Date picker             | -                                  |
| `boolean`       | Checkbox                | `FormFieldRule`                    |
| `select`        | Dropdown                | `FormFieldRule`                    |
| `multi_select`  | Multi-select dropdown   | `FormFieldRule`                    |
| `file`          | File upload             | -                                  |
| `email`         | Email with verification | `EmailVerificationRule`            |
| `phone`         | Phone with validation   | -                                  |
| `url`           | URL input               | -                                  |
| `currency`      | Money amount            | `VolumeRule`                       |
| `percentage`    | Percentage              | -                                  |
| `volume`        | Transaction volume      | `VolumeRule`                       |
| `country`       | Country selection       | `CountryRule`                      |
| `name`          | Name with list check    | `ListMatchRule`                    |
| `wallet`        | Crypto wallet           | Crypto validation                  |
| `document_id`   | ID number               | Format validation                  |
| `domain`        | Domain/URL              | `WebValidationRules`               |
| `address`       | Full address            | `CountryRule` (via country\_type)  |
| `entity_array`  | Directors/shareholders  | `ListMatchRule` (related\_parties) |
| `sub_merchant`  | Sub-merchant info       | Web validation                     |
| `array`         | Generic array           | -                                  |
| `nested_object` | Nested fields           | -                                  |

## Related Documentation

* [Step Types](/api-reference/workflows/steps) - Workflow step configuration
* [Automation Rules](/api-reference/workflows/automations) - Rules for automatic decisions
* [Examples](/api-reference/workflows/examples) - Complete workflow examples