# Forms

Forms enable tenant administrators to build custom dynamic form structures by mapping pre-configured attributes (such as text fields, dropdown choices, checkboxes, file uploads, etc.) to collect structured submissions from end-users or clients.

Forms support status lifecycle management (`draft`, `active`, `inactive`), custom slugs for friendly routing, required field validations, and full submission history tracking.

**Sample Form Object**

```json
{
  "id": 1,
  "title": "Customer Feedback Form",
  "description": "Feedback and satisfaction survey for platform users",
  "status": "active",
  "slug": "customer-feedback",
  "metadata": {},
  "created_at": 1723068000,
  "updated_at": 1723068000,
  "attributes": [
    {
      "id": 10,
      "form_id": 1,
      "attribute_id": 5,
      "required": true,
      "order_by": 1,
      "metadata": {},
      "attribute": {
        "id": 5,
        "field_type": "text",
        "type": "string",
        "optional": false,
        "icon_path": "",
        "active": true,
        "metadata": {},
        "values": []
      }
    }
  ]
}
```

**Sample Form Submission Object**

```json
{
  "id": 101,
  "submission_ref": "SUB-1723068000000-1234",
  "form_id": 1,
  "user_id": 42,
  "ip_address": "127.0.0.1",
  "user_agent": "Mozilla/5.0",
  "metadata": {},
  "created_at": 1723068000,
  "updated_at": 1723068000,
  "user": {
    "id": 42,
    "unique_id": "usr_42",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "attribute_values": [
    {
      "id": 201,
      "submission_id": 101,
      "form_id": 1,
      "attribute_id": 5,
      "values_": ["Great service!"],
      "attribute": {
        "id": 5,
        "field_type": "text",
        "type": "string"
      }
    }
  ]
}
```

## Form Object

| **attribute** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | Unique form ID. |
| `title` | `string` | Display title of the form. |
| `description` | `string` | Optional description or instructions for filling out the form. |
| `status` | `string` | Form status: `draft`, `active`, or `inactive`. Only `active` forms accept submissions. |
| `slug` | `string` | Friendly URL slug identifier for the form (e.g. `customer-feedback`). |
| `metadata` | `object` | Arbitrary JSON key-value store for tenant-specific form settings. |
| `attributes` | `array<FormAttribute>` | List of dynamic attributes and field validation constraints attached to the form. |
| `created_at` | `integer` | Unix epoch timestamp (in seconds) when the form was created. |
| `updated_at` | `integer` | Unix epoch timestamp (in seconds) when the form was last updated. |

## Form Attribute Object

| **attribute** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | Unique ID of the form attribute binding. |
| `form_id` | `integer` | ID of the parent form. |
| `attribute_id` | `integer` | ID of the linked master attribute. |
| `required` | `boolean` | Indicates whether submitting a value for this field is mandatory. |
| `order_by` | `integer` | Display order rank for rendering fields in form UI. |
| `metadata` | `object` | Custom attribute configuration metadata (e.g. placeholder text, validation regex). |
| `attribute` | `Attribute` | Full attribute definition object including field type, input constraints, and pre-defined options. |

## Form Submission Object

| **attribute** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | Unique submission record ID. |
| `submission_ref` | `string` | Unique public reference code generated for tracking (e.g. `SUB-1723068000000-1234`). |
| `form_id` | `integer` | ID of the form submitted against. |
| `user_id` | `integer` | ID of the user who submitted the form (`0` if anonymous submission). |
| `user` | `User` | Brief profile of the submitter user (`id`, `unique_id`, `first_name`, `last_name`, `email`). |
| `ip_address` | `string` | Client IP address at submission time. |
| `user_agent` | `string` | Client browser user agent string. |
| `metadata` | `object` | Additional metadata passed during submission. |
| `attribute_values` | `array<FormAttributeValue>` | List of submitted answer values for each form attribute. |
| `created_at` | `integer` | Unix epoch timestamp (in seconds) when the submission was recorded. |
| `updated_at` | `integer` | Unix epoch timestamp (in seconds) when the submission record was last updated. |

## Form Attribute Value Object

| **attribute** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | Unique attribute value record ID. |
| `submission_id` | `integer` | Parent submission ID. |
| `form_id` | `integer` | Parent form ID. |
| `attribute_id` | `integer` | ID of the attribute answered. |
| `values_` | `array<string>` | List of selected or entered answer strings for this field. |
| `attribute` | `Attribute` | Summary attribute object indicating `field_type` and `type`. |