Read and Write Worksheet Data via API
HAP provides APIs that allow developers to integrate worksheets with external systems. You can use these APIs to write data from external systems to worksheets or retrieve existing worksheet data.
Example Use Case
Suppose you have an Order Management app with an Orders worksheet that tracks both online and offline orders. You also use an online sales system to manage orders placed through your website.
Whenever a customer places an online order, you can use the Worksheet API to automatically create a corresponding record in the Orders worksheet. This eliminates manual data entry, saves time, and reduces the risk of errors.
API Documentation
App administrators can open the API documentation to view all available APIs for the current app.

App Authorization
HAP uses token-based authentication. The AppKey and SecretKey are provided in the app's API documentation. Super Admins can also regenerate these credentials.
Field and Control Type Reference

-
Field ID: A system-generated identifier for a field that cannot be changed. When writing data through an API, use the field ID to identify the target field.
-
Field Name: The name assigned to the field by the app administrator.
-
Type: The control type selected for the field.
-
Control Type ID: The numeric identifier of the control type, commonly used in API requests. Different control types may support different filtering methods.
-
Description: Information about the field, such as its data type, sample values, and whether it supports writing data.
-
Worksheet and Field Aliases: Worksheet IDs and field IDs are long strings that can be difficult to remember or enter. You can assign aliases to worksheets and fields and use these aliases in API requests instead of their IDs.
API for Adding Records
HAP provides more than 10 APIs to support various data operations.
The following example demonstrates how to create a new record in a worksheet using an API.

Request Guidelines
-
API Endpoint:
-
Request Parameters:
You can reuse the values provided on the right side of the API documentation for parameters such as
appkey,sign,worksheetid,controls, andcontrolId.Parameter names are automatically generated based on the current worksheet and should not be changed. When testing the API, you only need to modify the parameter values as needed.
Sample Request (Ready to Copy)
{
"appKey": "15d5b427b4bbf1b6",
"sign": "ZDRjZDEzM2Q3YzUzMGI1ZDhjOWNhOWQ2MzFiZDkxNDY1NmYyZjBiYjE1YzYzZGMxNGU0MmNjZDA2NjJmYjViNA==",
"worksheetId": "655c79654120176fa4758593",
"controls": [
{
"controlId": "6426808e315e39d1e4dae83e",
"value": "This is a test"
},
{
"controlId": "5e0a02642134520001e19345",
"value": "666.66"
}
],
"triggerWorkflow": true
}
Response Parameters and Sample Response
{
"data": "75f221fb-d645-4010-92cb-acced0c73cea",
"success": true
}
Error Codes
| ErrorCode | Description |
|---|---|
| 0 | Failed |
| 1 | Success |
| 10001 | Missing required parameters |
| 10002 | Invalid parameter value |
| 10005 | Insufficient permissions for data operations |
| 10007 | Data does not exist |
| 10101 | Request token does not exist |
| 10102 | Invalid signature |
| 99999 | Data operation error |
Test the API
In this example, we'll use an online API testing tool to simulate writing data from an external system to a worksheet.
We recommend https://hoppscotch.io, but you can use any API testing tool.

- Paste the API endpoint into the request URL field.
- Select POST as the request method.
- Select Body for the request payload.
- Set Content-Type to
application/json. - Paste the sample request code from the API documentation into the request body editor.
- Click Send to submit the request.
- Check the response displayed below. If it contains
"success": true, the record was created successfully. Refresh the worksheet to view the new record. Its creator will be displayed as API.
How to Obtain Related Parameters
When testing APIs, you may need specific parameter values, such as a View ID or Record ID (rowId).
Record ID (rowId)
Open the record details page, click Copy ID in the More menu to obtain the record ID.

View ID
A View ID is required when retrieving records from a specific view.
How to Find the View ID:
In the app's API documentation, go to App Authorization > Worksheet > Target Worksheet > View Information Table to find the View ID.

Was this document helpful?