This is an old revision of the document!
Table of Contents
1. Background & Objective
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
2. API Security Design
2.1 workspace_token
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.
2.2 Error Response Format
{
"error": "Invalid or missing workspace_token"
}
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
{
"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
}
]
}