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
}
]
}
API-002: Create Form Entry
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"
}
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
{
"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"
}
API-004: Query Form Entries
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
}
]
}
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
{
"workspace_id": "abc123",
"workspace_token": "xxxxx",
"internal_access_key": "internalSecretKey"
}
Success Response
{
"message": "Form result archived"
}
Unauthorized Response
{
"error": "Unauthorized access"
}
5. Acceptance Criteria
| ID | Acceptance Item | Verification Method |
|---|---|---|
| 1 | All APIs must enforce workspace_token | Test with missing token; should return an error |
| 2 | Field metadata can be retrieved successfully | Use valid workspace_id and form_id for testing |
| 3 | Form entry can be created successfully | Should return result_id; data retrievable via query |
| 4 | Existing form entry can be updated | Use valid result_id; verify field value is updated |
| 5 | Supports conditional query with pagination | Test using filters, limit, and offset parameters |
| 6 | Archive function restricted to internal use | Test without internal_access_key; should return error |