Differences

This shows you the differences between two versions of the page.

--- form_builder_api [2025/08/19 01:39] – created pr3
+++ form_builder_api [2025/08/26 04:42] (current) – pr3
@@ Line 32: / Line 32: @@
 }
 </code>
+===== 3. Features & API List =====
+^ API ID   ^ Feature Name          ^ Description                                    ^ Method ^ Example Path                                ^
+| [[API-001]]  | Get Field Metadata    | Retrieve field definitions for a specific form | POST   | /api/v1/form-results-value/metadata          |
+| API-002  | Create Form Entry     | Submit a new form response to a specific Workspace | POST   | /api/v1/form-results-value/create            |
+| API-003  | Update Form Entry     | Update an existing form entry by result_id     | PUT    | /api/v1/form-results-value/update/{result_id}|
+| API-004  | Query Form Entries    | Retrieve all or filtered form data             | POST   | /api/v1/form-results-value/query             |
+| API-005  | Archive Form Entry    | Mark form entry as archived (internal API only)| PATCH  | /api/v1/form-results-value/archive/{result_id}|
+===== 4. API Details =====
+==== API-001: Get Field Metadata ====
+**Method:** POST  \\
+**Endpoint:** `/api/v1/form-results-value/metadata`
+**Request Payload**
+<code json>
+{
+  "workspace_id": "abc123",
+  "form_id": "form456",
+  "workspace_token": "xxxxx"
+}
+</code>
+**Response**
+<code json>
+{
+  "form_name": "Customer Feedback",
+  "fields": [
+    {
+      "field_key": "email",
+      "label": "Email",
+      "type": "text",
+      "required": true
+    },
+    {
+      "field_key": "rating",
+      "label": "Rating",
+      "type": "number",
+      "required": false
+    }
+  ]
+}
+</code>
+==== API-002: Create Form Entry ====
+**Method:** POST
+**Endpoint:** `/api/v1/form-results-value/create`
+**Request Payload**
+<code json>
+{
+  "workspace_id": "abc123",
+  "form_id": "form456",
+  "workspace_token": "xxxxx",
+  "customer_email": "user@example.com",
+  "data": {
+    "email": "user@example.com",
+    "rating": 5,
+    "files": [
+      {
+        "name": "image1.jpg",
+        "url": "https://storage.example.com/file/image1.jpg",
+        "type": "image/jpeg",
+        "size": 1024000
+      },
+      {
+        "name": "document.pdf",
+        "url": "https://storage.example.com/file/document.pdf",
+        "type": "application/pdf",
+        "size": 2048000
+      }
+    ]
+  }
+}
+</code>
+**Note:** For any field with `type=upload`, you should call the File Upload API first and pass the response in the format above.
+See: [[Form Record File Upload API]]
+**Success Response**
+<code json>
+{
+  "message": "Form result created successfully",
+  "result_id": "xyz789"
+}
+</code>
+**Error Response**
+<code json>
+{
+  "error": "Missing required field: email"
+}
+</code>
+----
+==== API-003: Update Form Entry ====
+**Method:** PUT
+**Endpoint:** `/api/v1/form-results-value/update/{result_id}`
+**Path Parameter**
+^ Parameter  ^ Type   ^ Description                         ^ Required |
+| result_id  | string | Unique identifier of the record     | Yes      |
+**Request Payload**
+^ Field          ^ Type    ^ Description           ^ Required |
+| workspace_id   | string  | Workspace identifier | Yes       |
+| workspace_token| string  | Access token         | Yes       |
+| data           | object  | Key-value fields to update | Yes |
+**Example**
+<code json>
+{
+  "workspace_id": "abc123",
+  "workspace_token": "xxxxx",
+  "data": {
+    "rating": 4
+  }
+}
+</code>
+**Note:**
+The system will validate that each field in `data` matches the expected format from the form metadata.
+If a field value does not match its type, an error will be returned.
+**Success Response**
+<code json>
+{
+  "message": "Form result updated"
+}
+</code>
+**Error Responses**
+Examples:
+_Invalid value_
+<code json>
+{
+  "error": "Invalid value for field 'rating': expected type 'number'"
+}
+</code>
+_Missing token_
+<code json>
+{
+  "error": "Invalid or missing workspace_token"
+}
+</code>
+_Invalid field key_
+<code json>
+{
+  "error": "Field 'unknown_field' is not defined in the form"
+}
+</code>
+----
+==== API-004: Query Form Entries ====
+**Method:** POST
+**Endpoint:** `/api/v1/form-results-value/query`
+**Request Payload**
+<code json>
+{
+  "workspace_id": "abc123",
+  "form_id": "form456",
+  "workspace_token": "xxxxx",
+  "filters": {
+    "email": "user@example.com"
+  },
+  "limit": 10,
+  "offset": 0
+}
+</code>
+**Response**
+<code json>
+{
+  "total": 1,
+  "data": [
+    {
+      "result_id": "xyz789",
+      "email": "user@example.com",
+      "rating": 5
+    }
+  ]
+}
+</code>
+----
+==== API-005: Archive Form Entry (Internal Use Only) ====
+**Method:** PATCH
+**Endpoint:** `/api/v1/form-results-value/archive/{result_id}`
+**Path Parameter**
+* `result_id`: ID of the record to archive
+**Request Payload**
+<code json>
+{
+  "workspace_id": "abc123",
+  "workspace_token": "xxxxx",
+  "internal_access_key": "internalSecretKey"
+}
+</code>
+**Success Response**
+<code json>
+{
+  "message": "Form result archived"
+}
+</code>
+**Unauthorized Response**
+<code json>
+{
+  "error": "Unauthorized access"
+}
+</code>
+----