Field Types - KYC API Documentation

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

Basic Fields

Standard inputs: text, number, date, boolean, select, file

Contact Fields

Email, phone, URL with validation options

Semantic Fields

Country, name, wallet, domain with automatic rule integration

Complex Fields

Address, entity arrays, sub-merchants, nested objects

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

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.

Basic Fields

Text Field

Simple text input.

{
  "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.

{
  "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.

{
  "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.

{
  "field_id": "terms_accepted",
  "name": "I accept the Terms and Conditions",
  "type": "boolean",
  "required": true
}

Select Field

Dropdown selection with predefined options.

{
  "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.

{
  "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.

{
  "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.

{
  "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.)

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

Phone Field

Phone number input with validation options.

{
  "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.

{
  "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.

{
  "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

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

Name Field

Name input with automatic sanctions/adverse media validation.

{
  "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

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

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.

Wallet Field

Cryptocurrency wallet address input.

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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.

{
  "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

Volume fields with apply_volume_rules: true will trigger matching VolumeRule automation rules during session processing.

Complex Fields

Address Field

Complete address input with optional country-based automation.

{
  "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).

{
  "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

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

Sub-Merchant Field

Sub-merchant information for payment facilitator onboarding.

{
  "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.

{
  "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.

{
  "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.

{
  "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	-

Step Types - Workflow step configuration
Automation Rules - Rules for automatic decisions
Examples - Complete workflow examples

​Field Categories

Basic Fields

Contact Fields

Semantic Fields

Complex Fields

​Common Field Properties

​Basic Fields

​Text Field

​Number Field

​Date Field

​Boolean Field

​Select Field

​Multi-Select Field

​File Field

​Contact Fields

​Email Field

​Phone Field

​URL Field

​Semantic Fields

​Country Field

​Country Types

​Name Field

​Wallet Field

​Document ID Field

​Domain Field

​Financial Fields

​Currency Field

​Percentage Field

​Volume Field

​Complex Fields

​Address Field

​Entity Array Field

​Sub-Merchant Field

​Array Field

​Nested Object Field

​Conditional Logic

​Conditional Operators

​Field Types Reference

​Related Documentation

Field Categories

Common Field Properties

Basic Fields

Text Field

Number Field

Date Field

Boolean Field

Select Field

Multi-Select Field

File Field

Contact Fields

Email Field

Phone Field

URL Field

Semantic Fields

Country Field

Country Types

Name Field

Wallet Field

Document ID Field

Domain Field

Financial Fields

Currency Field

Percentage Field

Volume Field

Complex Fields

Address Field

Entity Array Field

Sub-Merchant Field

Array Field

Nested Object Field

Conditional Logic

Conditional Operators

Field Types Reference

Related Documentation