> For the complete documentation index, see [llms.txt](https://docs.acpt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acpt.io/integrations/abilities-api/forms.md).

# Forms

acpt/list-forms, acpt/get-form, acpt/save-form, acpt/delete-form, acpt/get-form-field, acpt/save-form-field, acpt/delete-form-field

Category: `acpt-content-model` · Default capability: `manage_options`

| Ability                  | What it does                                                                     |
| ------------------------ | -------------------------------------------------------------------------------- |
| `acpt/list-forms`        | Returns every ACPT form                                                          |
| `acpt/get-form`          | Returns a single form by name, including its fields                              |
| `acpt/save-form`         | Creates a form, or updates it if the name already exists                         |
| `acpt/delete-form`       | Deletes a form and its fields                                                    |
| `acpt/get-form-field`    | Returns a single field of a form                                                 |
| `acpt/save-form-field`   | Creates a field on a form, or updates it if the name already exists on that form |
| `acpt/delete-form-field` | Deletes a field from a form                                                      |

{% hint style="info" %}
There's no `acpt/list-form-fields` ability — `acpt/get-form` already returns the form's full `fields` array, so a dedicated listing ability would just duplicate it.
{% endhint %}

## acpt/list-forms

No input required.

```php
$result = wp_get_ability('acpt/list-forms')->execute();
```

## acpt/get-form

**Input**

| Property | Type   | Required |
| -------- | ------ | -------- |
| `name`   | string | Yes      |

```php
$result = wp_get_ability('acpt/get-form')->execute([
    'name' => 'contact-us',
]);
```

```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "e4f5a6b7-8901-4abc-9def-0123456789ab",
    "name": "contact-us",
    "key": "a1b2c3d4",
    "label": "Contact us",
    "action": "EMAIL",
    "fields": [
      {
        "id": "f5a6b7c8-9012-4abc-9def-0123456789ab",
        "group": "main",
        "name": "email",
        "key": "e1",
        "label": "Your email",
        "type": "Email",
        "isRequired": true
      }
    ],
    "fieldsCount": 1,
    "meta": [],
    "submissions": []
  }
}
```

## acpt/save-form

**Input**

| Property | Type   | Required | Notes                                                                                                      |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `name`   | string | Yes      | If a form with this name already exists, it's **updated** instead of duplicated                            |
| `key`    | string | Yes      | Unique form key, used in the `[acpt_form]` shortcode and the public form-submission REST endpoint          |
| `action` | string | Yes      | `NONE`, `EMAIL`, `PHP`, `AJAX`, `CUSTOM`, or `FILL_META` — what happens when the form is submitted         |
| `label`  | string | No       |                                                                                                            |
| `fields` | array  | No       | Field definitions — see [`acpt/save-form-field`](#acptsave-form-field) for the shape of each item          |
| `meta`   | array  | No       | Form-level metadata (email settings, submission limits, etc. — see [Manage forms](/forms/manage-forms.md)) |

```php
$result = wp_get_ability('acpt/save-form')->execute([
    'name'   => 'contact-us',
    'key'    => 'a1b2c3d4',
    'label'  => 'Contact us',
    'action' => 'EMAIL',
]);
```

## acpt/delete-form

**Input**

| Property | Type   | Required |
| -------- | ------ | -------- |
| `name`   | string | Yes      |

```php
$result = wp_get_ability('acpt/delete-form')->execute([
    'name' => 'contact-us',
]);
```

## acpt/get-form-field

**Input**

| Property    | Type   | Required |
| ----------- | ------ | -------- |
| `formName`  | string | Yes      |
| `fieldName` | string | Yes      |

```php
$result = wp_get_ability('acpt/get-form-field')->execute([
    'formName'  => 'contact-us',
    'fieldName' => 'email',
]);
```

## acpt/save-form-field

**Input**

| Property          | Type    | Required | Notes                                                                                                                                                                                                   |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formName`        | string  | Yes      | The form this field belongs to                                                                                                                                                                          |
| `group`           | string  | Yes      | The canvas group/section this field is placed in                                                                                                                                                        |
| `name`            | string  | Yes      | If a field with this name already exists **on that form**, it's updated instead of duplicated                                                                                                           |
| `key`             | string  | Yes      |                                                                                                                                                                                                         |
| `type`            | string  | Yes      | e.g. `Text`, `Email`, `Textarea`, `Select`, `File`, `Date`, `Address`, `Captcha`, or a WordPress-bound type like `Post` / `User` — see [The form builder](/forms/the-form-builder.md) for the full list |
| `isRequired`      | boolean | Yes      |                                                                                                                                                                                                         |
| `label`           | string  | No       |                                                                                                                                                                                                         |
| `description`     | string  | No       |                                                                                                                                                                                                         |
| `extra`           | array   | No       | Type-specific extra settings (default value, placeholder, etc.)                                                                                                                                         |
| `settings`        | array   | No       | Layout settings (alignment, columns, CSS classes, …)                                                                                                                                                    |
| `validationRules` | array   | No       | See [Validation rules](/meta-fields/the-meta-fields-manager/validation-rules-fields-settings.md)                                                                                                        |

```php
$result = wp_get_ability('acpt/save-form-field')->execute([
    'formName'   => 'contact-us',
    'group'      => 'main',
    'name'       => 'email',
    'key'        => 'e1',
    'type'       => 'Email',
    'label'      => 'Your email',
    'isRequired' => true,
]);
```

## acpt/delete-form-field

**Input**

| Property    | Type   | Required |
| ----------- | ------ | -------- |
| `formName`  | string | Yes      |
| `fieldName` | string | Yes      |

```php
$result = wp_get_ability('acpt/delete-form-field')->execute([
    'formName'  => 'contact-us',
    'fieldName' => 'email',
]);
```