> ## Documentation Index > Fetch the complete documentation index at: https://docs.directify.app/llms.txt > Use this file to discover all available pages before exploring further. # Custom Fields API – Directify REST Reference > Retrieve, create, update, and delete custom fields on your directory through the Directify REST API. Full request/response schema with examples. ## Custom Fields ### Get Directory Custom Fields Retrieve all custom fields for a specific directory. ```http theme={null} GET /api/directories/{directory_id}/custom-fields ``` **Parameters:** * `directory_id` (integer, required): The ID of the directory **Response:** ```json theme={null} { "data": [ { "id": 1, "directory_id": 1, "fieldable_type": "listing", "name": "pricing", "label": "Pricing", "type": "text", "placeholder": "Enter pricing information", "description": "Pricing details for the tool", "default_value": null, "placement": "after_tags", "placement_on_card": "before_buttons", "is_required": false, "is_visible": true, "show_on_card": true, "show_on_public_submission": false, "show_label": false, "show_label_on_card": true, "show_icon": false, "show_icon_on_card": false, "icon": null, "order": 1, "options": null, "created_at": "2024-01-15T10:30:00.000000Z", "updated_at": "2024-01-15T10:30:00.000000Z" }, { "id": 2, "directory_id": 1, "fieldable_type": "listing", "name": "job_type", "label": "Job Type", "type": "select", "placeholder": "Select job type", "description": "Type of employment", "default_value": null, "placement": "after_tags", "placement_on_card": "before_buttons", "is_required": true, "is_visible": true, "show_on_card": true, "show_on_public_submission": true, "show_label": true, "show_label_on_card": true, "show_icon": false, "show_icon_on_card": false, "icon": null, "order": 2, "options": [ "Full-time", "Part-time", "Contract", "Freelance", "Internship" ], "created_at": "2024-01-15T10:30:00.000000Z", "updated_at": "2024-01-15T10:30:00.000000Z" } ] } ``` ### Get Single Custom Field Retrieve a specific custom field by ID. ```http theme={null} GET /api/directories/{directory_id}/custom-fields/{custom_field_id} ``` **Parameters:** * `directory_id` (integer, required): The ID of the directory * `custom_field_id` (integer, required): The ID of the custom field ### Create Custom Field Create a new custom field definition in the directory. ```http theme={null} POST /api/directories/{directory_id}/custom-fields ``` **Parameters:** * `directory_id` (integer, required): The ID of the directory **Request Body:** ```json theme={null} { "label": "Price Range", "type": "select", "options": ["$", "$$", "$$$"], "fieldable_type": "listing", "placeholder": "Select a price range", "description": "Typical cost per person", "default_value": null, "value_prefix": "", "value_suffix": "", "is_required": false, "is_visible": true, "show_on_card": true, "show_on_public_submission": true, "filterable": true, "order": 3 } ``` **Available fields:** | Field | Type | Description | | --------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | string, required | Human-readable field label shown to users | | `type` | string, required | Field type (see [Custom Field Types](#custom-field-types)) | | `name` | string | Machine key used when setting values on listings. Auto-derived from `label` (lowercased, snake\_cased) if omitted — e.g. `"Price Range"` → `price_range` | | `fieldable_type` | string | What the field attaches to: `listing` (default), `organizer`, or `article` | | `placeholder` | string | Input placeholder text | | `description` | string | Help text shown under the field | | `default_value` | string | Default value | | `value_prefix` | string | Prefix shown before the value (e.g. `$`) | | `value_suffix` | string | Suffix shown after the value (e.g. `/mo`) | | `options` | array | Choices for `select`, `multi_select`, and `list` types | | `is_required` | boolean | Whether the field is required | | `is_visible` | boolean | Whether the field shows on the listing page (default: true) | | `show_on_card` | boolean | Show the value on listing cards | | `show_on_public_submission` | boolean | Show the field on the public submission form | | `show_label` | boolean | Show the label on the listing page | | `show_label_on_card` | boolean | Show the label on cards | | `show_icon` | boolean | Show the field's icon on the listing page | | `show_icon_on_card` | boolean | Show the field's icon on cards | | `filterable` | boolean | Allow filtering listings by this field | | `placement` | string | Where the field renders on the listing page: `after_tags`, `after_categories`, `before_content`, or `after_content` | | `placement_on_card` | string | Where the value renders on the card: `after_title`, `before_categories`, `after_categories`, `before_buttons`, or `after_buttons` | | `icon` / `heroicon` | string | Field icon — an emoji or image URL (`icon`), or a Heroicon name such as `heroicon-o-currency-dollar` (`heroicon`) | | `order` | integer | Sort order among fields | | `validation_rules` | array | Extra [Laravel validation rules](https://laravel.com/docs/validation#available-validation-rules) applied to the value, e.g. `["min:3", "max:80"]` | | `settings` | object | Extra per-type settings | After creating a field, set its value on a listing by passing the field's `name` as a flat key in the listing's create/update body — e.g. `{ "name": "My Tool", "price_range": "$$" }`. See [Listings → Create Listing](/api-integration/projects#create-listing). ### Update Custom Field Update an existing custom field definition. Only include the fields you want to change. ```http theme={null} PUT /api/directories/{directory_id}/custom-fields/{custom_field_id} ``` **Request Body:** ```json theme={null} { "label": "Pricing Tier", "is_required": true, "options": ["Free", "Pro", "Enterprise"] } ``` ### Delete Custom Field Delete a custom field definition. This also removes the field's stored values from all listings. ```http theme={null} DELETE /api/directories/{directory_id}/custom-fields/{custom_field_id} ``` **Response:** ```json theme={null} { "message": "Custom field deleted successfully" } ``` ## Custom Field Types The API supports various custom field types: * `text` - Simple text input * `number` - Numeric input * `date` - Date picker * `file_upload` - File upload field * `url` - URL input with validation * `email` - Email input with validation * `rich_editor` - Rich text editor * `markdown` - Markdown editor * `textarea` - Multi-line text area * `checkbox` - Boolean toggle * `rating` - Rating input (0-5) * `select` - Dropdown with predefined options * `list` - Repeatable list of values * `multi_select` - Multiple-choice select (stored comma-separated) * `button` - Button/CTA field * `javascript` - Custom JavaScript * `html` - Custom HTML