To support platform integration and workflow automation for MCW, CX Genie must provide open APIs for third-party systems to perform the following operations on form data:

• Retrieve form field metadata
• Create new form entries
• Update specific form entries
• Query all or filtered form data
• Archive form entries (internal use only)

These APIs will be applied in scenarios such as:

• Data synchronization
• Auto-fill features
• Self-service queries

Authentication All API requests must include the following field in the request payload:

"workspace_token": "your_token_here"

The system will verify the token against the corresponding Workspace’s permissions. Requests with invalid or missing tokens will return a 401 Unauthorized error.

{
  "error": "Invalid or missing workspace_token"
}

Method: POST
Endpoint: `/api/v1/form-results-value/metadata`

Request Payload

{
  "workspace_id": "abc123",
  "form_id": "form456",
  "workspace_token": "xxxxx"
}

Response

{
  "form_name": "Customer Feedback",
  "fields": [
    {
      "field_key": "email",
      "label": "Email",
      "type": "text",
      "required": true
    },
    {
      "field_key": "rating",
      "label": "Rating",
      "type": "number",
      "required": false
    }
  ]
}

Method: POST Endpoint: `/api/v1/form-results-value/create`

Request Payload

{
  "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
      }
    ]
  }
}

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

{
  "message": "Form result created successfully",
  "result_id": "xyz789"
}

Error Response

{
  "error": "Missing required field: email"
}

Method: PUT Endpoint: `/api/v1/form-results-value/update/{result_id}`

Path Parameter

Request Payload

Example

{
  "workspace_id": "abc123",
  "workspace_token": "xxxxx",
  "data": {
    "rating": 4
  }
}

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

{
  "message": "Form result updated"
}

Error Responses Examples:

_Invalid value_

{
  "error": "Invalid value for field 'rating': expected type 'number'"
}

_Missing token_

{
  "error": "Invalid or missing workspace_token"
}

_Invalid field key_

{
  "error": "Field 'unknown_field' is not defined in the form"
}

Method: POST Endpoint: `/api/v1/form-results-value/query`

Request Payload

{
  "workspace_id": "abc123",
  "form_id": "form456",
  "workspace_token": "xxxxx",
  "filters": {
    "email": "user@example.com"
  },
  "limit": 10,
  "offset": 0
}

Response

{
  "total": 1,
  "data": [
    {
      "result_id": "xyz789",
      "email": "user@example.com",
      "rating": 5
    }
  ]
}

Method: PATCH Endpoint: `/api/v1/form-results-value/archive/{result_id}`

Path Parameter * `result_id`: ID of the record to archive

Request Payload

{
  "workspace_id": "abc123",
  "workspace_token": "xxxxx",
  "internal_access_key": "internalSecretKey"
}

Success Response

{
  "message": "Form result archived"
}

Unauthorized Response

{
  "error": "Unauthorized access"
}