[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / CustomFieldDefinitionManager

# Class: CustomFieldDefinitionManager

Custom Field Definition Manager - Manage tenant-specific custom fields

Provides CRUD operations for custom field definitions that extend the built-in
user profile fields. Custom fields are defined per-tenant and can be used for
additional user data collection, redemption requirements, and form validation.

**`Example`**

```typescript
// List all user custom fields
const fields = await sdk.customFields.getDefinitions();

// Create a new custom field
const field = await sdk.customFields.createDefinition({
  key: 'employee_id',
  label: 'Employee ID',
  fieldType: 'text',
  validation: { required: true, pattern: '^E[0-9]{5}$' }
});

// Update a field
await sdk.customFields.updateDefinition(field.id, {
  label: 'Company Employee ID'
});

// Delete a field
await sdk.customFields.deleteDefinition(field.id);
```

**`Example`**

```typescript
// Validate user custom data against definitions
const definitions = await sdk.customFields.getDefinitions();
const errors = sdk.customFields.validateUserData(
  { employee_id: 'INVALID' },
  definitions
);
if (errors.length > 0) {
  console.log('Validation errors:', errors);
}
```

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/customfielddefinitionmanager#constructor)


### Methods

- [getDefinitions](/sdk-reference/classes/customfielddefinitionmanager#getdefinitions)
- [getDefinition](/sdk-reference/classes/customfielddefinitionmanager#getdefinition)
- [createDefinition](/sdk-reference/classes/customfielddefinitionmanager#createdefinition)
- [updateDefinition](/sdk-reference/classes/customfielddefinitionmanager#updatedefinition)
- [deleteDefinition](/sdk-reference/classes/customfielddefinitionmanager#deletedefinition)
- [resolveSelectOptions](/sdk-reference/classes/customfielddefinitionmanager#resolveselectoptions)
- [validateUserData](/sdk-reference/classes/customfielddefinitionmanager#validateuserdata)
- [validateFieldValue](/sdk-reference/classes/customfielddefinitionmanager#validatefieldvalue)


## Constructors

### constructor

• **new CustomFieldDefinitionManager**(`apiClient`, `events?`): [`CustomFieldDefinitionManager`](/sdk-reference/classes/customfielddefinitionmanager)

#### Parameters

| Name | Type |
|  --- | --- |
| `apiClient` | [`PersApiClient`](/sdk-reference/classes/persapiclient) |
| `events?` | [`PersEventEmitter`](/sdk-reference/classes/perseventemitter) |


#### Returns

[`CustomFieldDefinitionManager`](/sdk-reference/classes/customfielddefinitionmanager)

#### Defined in

[managers/custom-field-definition-manager.ts:83](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L83)

## Methods

### getDefinitions

▸ **getDefinitions**(`options?`): `Promise`<`CustomFieldDefinitionDTO`[]>

List all custom field definitions for the tenant

Retrieves all custom field definitions, optionally filtered by entity type.
Results are sorted by sortOrder (ascending).

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | [`CustomFieldQueryOptions`](/sdk-reference/interfaces/customfieldqueryoptions) | Query options including entity type filter |


#### Returns

`Promise`<`CustomFieldDefinitionDTO`[]>

Array of custom field definitions

**`Example`**

```typescript
const fields = await sdk.customFields.getDefinitions();
console.log(`Found ${fields.length} custom fields`);

fields.forEach(field => {
  console.log(`${field.key}: ${field.label} (${field.fieldType})`);
});
```

**`Example`**

```typescript
// Get only business custom fields
const businessFields = await sdk.customFields.getDefinitions({
  entityType: 'business'
});
```

#### Defined in

[managers/custom-field-definition-manager.ts:117](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L117)

### getDefinition

▸ **getDefinition**(`id`): `Promise`<`CustomFieldDefinitionDTO`>

Get a single custom field definition by ID

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `id` | `string` | The UUID of the custom field definition |


#### Returns

`Promise`<`CustomFieldDefinitionDTO`>

The custom field definition

**`Throws`**

When definition not found (404)

**`Example`**

```typescript
try {
  const field = await sdk.customFields.getDefinition('uuid-here');
  console.log('Field:', field.label);
} catch (error) {
  if (error.statusCode === 404) {
    console.log('Field not found');
  }
}
```

#### Defined in

[managers/custom-field-definition-manager.ts:142](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L142)

### createDefinition

▸ **createDefinition**(`data`): `Promise`<`CustomFieldDefinitionDTO`>

Create a new custom field definition

Creates a new custom field for the tenant. The field key must be unique
within the tenant and entity type combination.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `data` | `CreateCustomFieldDefinitionDTO` | The field definition data |


#### Returns

`Promise`<`CustomFieldDefinitionDTO`>

The created custom field definition

**`Throws`**

When key already exists (409) or validation fails (400)

**`Example`**

```typescript
const employeeIdField = await sdk.customFields.createDefinition({
  key: 'employee_id',
  label: 'Employee ID',
  description: 'Your company employee ID (E + 5 digits)',
  fieldType: 'text',
  validation: {
    required: true,
    pattern: '^E[0-9]{5}$',
    patternMessage: 'Must be E followed by 5 digits'
  },
  sortOrder: 1
});
```

**`Example`**

```typescript
const checkOutField = await sdk.customFields.createDefinition({
  key: 'check_out',
  label: 'Check-out Date',
  fieldType: 'date',
  validation: {
    required: true,
    comparisons: [
      { field: 'check_in', operator: '>', message: 'Must be after check-in' }
    ]
  },
  sortOrder: 2
});
```

**`Example`**

```typescript
const departmentField = await sdk.customFields.createDefinition({
  key: 'department',
  label: 'Department',
  fieldType: 'select',
  selectOptions: [
    { value: 'engineering', label: 'Engineering' },
    { value: 'sales', label: 'Sales' },
    { value: 'hr', label: 'Human Resources' }
  ],
  validation: { required: true }
});
```

**`Example`**

```typescript
const hotelField = await sdk.customFields.createDefinition({
  key: 'preferred_hotel',
  label: 'Preferred Hotel',
  fieldType: 'select',
  selectOptionsSource: {
    entity: 'business',
    valueField: 'id',
    labelField: 'name',
    filter: { tags: ['hotel'], isActive: true }
  },
  validation: { required: true }
});
```

#### Defined in

[managers/custom-field-definition-manager.ts:219](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L219)

### updateDefinition

▸ **updateDefinition**(`id`, `data`): `Promise`<`CustomFieldDefinitionDTO`>

Update an existing custom field definition

Updates a custom field definition. Note that key and entityType cannot
be changed after creation.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `id` | `string` | The UUID of the custom field definition to update |
| `data` | `UpdateCustomFieldDefinitionDTO` | The fields to update (partial update supported) |


#### Returns

`Promise`<`CustomFieldDefinitionDTO`>

The updated custom field definition

**`Throws`**

When definition not found (404) or validation fails (400)

**`Example`**

```typescript
const updated = await sdk.customFields.updateDefinition('uuid-here', {
  label: 'Employee ID (Required)',
  validation: {
    required: true,
    minLength: 6,
    maxLength: 6
  }
});
```

**`Example`**

```typescript
await sdk.customFields.updateDefinition('uuid-here', {
  sortOrder: 5
});
```

#### Defined in

[managers/custom-field-definition-manager.ts:265](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L265)

### deleteDefinition

▸ **deleteDefinition**(`id`): `Promise`<`void`>

Delete a custom field definition (soft delete)

Soft deletes a custom field definition. Existing user data in customData
is preserved, but the field will no longer appear in forms or validation.

⚠️ Consider the impact on existing user data before deleting.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `id` | `string` | The UUID of the custom field definition to delete |


#### Returns

`Promise`<`void`>

**`Throws`**

When definition not found (404)

**`Example`**

```typescript
try {
  await sdk.customFields.deleteDefinition('uuid-here');
  console.log('Field deleted');
} catch (error) {
  console.log('Failed to delete:', error.message);
}
```

#### Defined in

[managers/custom-field-definition-manager.ts:303](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L303)

### resolveSelectOptions

▸ **resolveSelectOptions**(`id`): `Promise`<`CustomFieldSelectOption`[]>

Resolve dynamic select options for a field

For fields with selectOptionsSource (dynamic options from entities),
this resolves the actual options by querying the source entity.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `id` | `string` | The UUID of the custom field definition |


#### Returns

`Promise`<`CustomFieldSelectOption`[]>

Array of select options

**`Example`**

```typescript
const field = await sdk.customFields.getDefinition('hotel-field-id');

if (field.selectOptionsSource) {
  // Options come from entity - need to resolve
  const options = await sdk.customFields.resolveSelectOptions(field.id);
  console.log('Available hotels:', options);
} else {
  // Static options
  console.log('Options:', field.selectOptions);
}
```

#### Defined in

[managers/custom-field-definition-manager.ts:338](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L338)

### validateUserData

▸ **validateUserData**(`data`, `definitions`): `ValidationErrorDetail`[]

Validate user custom data against field definitions

Client-side validation using the same rules as the backend. Use this
to validate form data before submission.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `data` | `Record`<`string`, `unknown`> | User's custom data (key-value pairs) |
| `definitions` | `CustomFieldDefinitionDTO`[] | Custom field definitions to validate against |


#### Returns

`ValidationErrorDetail`[]

Array of validation errors (empty if valid)

**`Example`**

```typescript
const definitions = await sdk.customFields.getDefinitions();
const formData = {
  employee_id: 'E123', // Missing a digit
  department: 'engineering'
};

const errors = sdk.customFields.validateUserData(formData, definitions);
if (errors.length > 0) {
  errors.forEach(err => {
    console.log(`${err.field}: ${err.message}`);
  });
  return; // Don't submit
}

// No errors, safe to submit
await sdk.users.updateCurrentUser({ customData: formData });
```

#### Defined in

[managers/custom-field-definition-manager.ts:373](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L373)

### validateFieldValue

▸ **validateFieldValue**(`value`, `definition`): `null` | `ValidationErrorDetail`

Validate a single field value

Validates a single value against a field's rules. Useful for
real-time validation as the user types.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `value` | `unknown` | The value to validate |
| `definition` | `CustomFieldDefinitionDTO` | The field definition |


#### Returns

`null` | `ValidationErrorDetail`

Validation error or null if valid

**`Example`**

```typescript
const employeeIdField = definitions.find(d => d.key === 'employee_id');

const handleBlur = (value: string) => {
  const error = sdk.customFields.validateFieldValue(value, employeeIdField);
  if (error) {
    setFieldError('employee_id', error.message);
  } else {
    clearFieldError('employee_id');
  }
};
```

#### Defined in

[managers/custom-field-definition-manager.ts:412](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/custom-field-definition-manager.ts#L412)