### Example JSON Response for Dataset Records Source: https://api.kissflow.com/ This is an example of the JSON response structure when retrieving dataset records. It includes filter information, table data, and column definitions. ```json { "Filter": {}, "Table_TableName": [ { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] }, { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] } ], "Columns": [ { "Id": "", "Type": "", "IsSystemField": "", "Name": "" }, { "Id": "", "Type": "", "IsSystemField": "", "Name": "" } ] } ``` -------------------------------- ### Get all dataset records Source: https://api.kissflow.com/ Retrieves all records of a specific dataset, including dataset fields and their corresponding values. Supports filtering, pagination, and field-specific search. ```APIDOC ## GET /dataset/2/:account_id/:dataset_id/list ### Description Retrieves all records of a specific dataset, including dataset fields and their corresponding values. ### Method GET ### Endpoint https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/list ### Parameters #### Path Parameters - **account_id** (string) - Required - Kissflow Account ID. - **dataset_id** (string) - Required - The unique identifier for each dataset. #### Query Parameters - **q** (string) - Optional - This is the search filter string. - **page_number** (integer) - Optional - This is the specific page number of an item list. Default value is 1. - **page_size** (integer) - Optional - The number of items that can be listed in a page result. Default value is 10. - **search_field** (string) - Optional - This is the search filter string based on specific field. #### Headers - **Accept** (string) - application/json - **X-Access-Key-Id** (string) - Required - Access key ID - **X-Access-Key-Secret** (string) - Required - Access key secret ### Request Example ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/list?q=%3Cstring%3E&page_number=%3Cinteger%3E&page_size=%3Cinteger%3E&search_field=%3Cstring%3E' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' ``` ### Response #### Success Response (200) - **Filter** (object) - **Table_TableName** (array of objects) - **response** (array of objects) - **Name** (string) - **_id** (string) - **PONumber** (string) - **TotalPrice** (string) - **RequestedBy** (object) - **_id** (string) - **Name** (string) - **Columns** (array of objects) - **Id** (string) - **Type** (string) - **IsSystemField** (boolean) - **Name** (string) ### Response Example ```json { "Filter": {}, "Table_TableName": [ { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] }, { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] } ], "Columns": [ { "Id": "", "Type": "", "IsSystemField": "", "Name": "" }, { "Id": "", "Type": "", "IsSystemField": "", "Name": "" } ] } ``` ``` -------------------------------- ### Testing APIs with cURL and HTTPie Source: https://api.kissflow.com/ Instructions on how to test Kissflow APIs directly from the terminal using cURL and HTTPie. ```APIDOC ## Testing APIs You can test APIs directly from the terminal using the cURL and HTTPie native tester tools. They allow you to send various HTTP requests and see the responses directly in your terminal. Follow these steps to execute API calls: * Under the Authorization tab in the right panel, enter the "Access Key ID" and "Secret Access Key" for HTTP request header authentication. * Use the example in the cURL or HTTPie command line terminal and edit the HTTP request to the server. * Click the **Try It** button. ``` -------------------------------- ### API Essentials Source: https://api.kissflow.com/ Understanding the core principles and requirements for interacting with Kissflow APIs, including HTTP methods and data formats. ```APIDOC ## API Essentials To effectively interact with APIs, the following developer requirements are recommended: **Programming knowledge**: Basic proficiency in programming languages such as JavaScript, Python, Ruby, Java, or others, depending on the API's technology stack. **Understanding HTTP and REST principles**: Familiarity with HTTP methods (GET, POST, PUT, DELETE) and RESTful principles. HTTP method | Description ---|--- GET | Retrieves data from a resource POST | Creates a new resource or initiates an action PUT | Updates a resource DELETE | Deletes a resource **JSON data format**: Ability to generate, parse, and manipulate JSON data format (JavaScript Object Notation) used for data exchange in APIs. **Authentication and security:** Knowledge of authentication methods (e.g., OAuth, API keys, basic authentication) and best practices for securing API endpoints. **Tools and libraries**: Knowledge of tools and libraries for making HTTP requests (e.g., cURL, Postman) and handling API responses. **Error handling and debugging**: Skills in troubleshooting API interactions, handling errors, and debugging issues that may arise during API integration. ``` -------------------------------- ### POST Bulk Update Dataset View Records Source: https://api.kissflow.com/ This endpoint allows bulk creation/update of up to 500 fields and values for a specified dataset view. It requires `Content-Type: multipart/form-data`. ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/view/:view_id/batch' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="[object Object]"' \ --form '1="[object Object]"' ``` -------------------------------- ### POST Bulk update records of a dataset view Source: https://api.kissflow.com/ This endpoint lets you bulk create/update up to 500 fields and values of a specified dataset view. ```APIDOC ## POST /dataset/2/:account_id/:dataset_id/view/:view_id/batch ### Description Lets you bulk create or update up to 500 fields and values of a specified dataset view. ### Method POST ### Endpoint `https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/view/:view_id/batch` ### Headers - **Content-Type**: `multipart/form-data` (Required) - **Accept**: `application/json` (Required) - **X-Access-Key-Id**: `` (Required) - Access key ID - **X-Access-Key-Secret**: `` (Required) - Access key secret ### Path Variables - **account_id** (``, Required) - Kissflow Account ID. - **dataset_id** (``, Required) - The unique identifier for each dataset. - **view_id** (``, Required) - The unique identifier for each dataset view. ### Request Body - **Record** (`[Object]`, Required) - Add a dataform record in the body payload. ### Request Example ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/view/:view_id/batch' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="[object Object]"' \ --form '1="[object Object]"' ``` ### Response #### Success Response (200) - **Body**: `application/json` #### Response Example ```json [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] ``` ``` -------------------------------- ### POST Bulk Update Dataset Records Source: https://api.kissflow.com/ Use this endpoint to create or update up to 500 dataset records per request. Provide an existing `_id` to update or a new `_id` to create a record. Requires `Content-Type: multipart/form-data`. ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/batch' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="[object Object]"' \ --form '1="[object Object]"' ``` -------------------------------- ### Retrieve Dataset Records with cURL Source: https://api.kissflow.com/ Use this cURL command to retrieve all records from a specific dataset. Ensure you replace placeholder values for account ID, dataset ID, and authentication headers. ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/list?q=%3Cstring%3E&page_number=%3Cinteger%3E&page_size=%3Cinteger%3E&search_field=%3Cstring%3E' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' ``` -------------------------------- ### POST Bulk update dataset records Source: https://api.kissflow.com/ This endpoint allows you to create or update up to 500 dataset records per request. It uses the `_id` field to determine the action: providing an existing `_id` updates the current record, while providing a new `_id` creates a new one. ```APIDOC ## POST /dataset/2/:account_id/:dataset_id/batch ### Description Allows bulk creation or update of up to 500 dataset records. Uses `_id` to determine if a record should be updated (existing `_id`) or created (new `_id`). ### Method POST ### Endpoint `https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/batch` ### Headers - **Content-Type**: `multipart/form-data` (Required) - **Accept**: `application/json` (Required) - **X-Access-Key-Id**: `` (Required) - Access key ID - **X-Access-Key-Secret**: `` (Required) - Access key secret ### Path Variables - **account_id** (``, Required) - Kissflow Account ID. - **dataset_id** (``, Required) - The unique identifier for each dataset. ### Request Body - **Data** (`[Object]`, Required) - Add records to the body payload. ### Request Example ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/batch' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="[object Object]"' \ --form '1="[object Object]"' ``` ### Response #### Success Response (200) - **Body**: `application/json` #### Response Example ```json [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] ``` ``` -------------------------------- ### Fundamental Data Types Source: https://api.kissflow.com/ Overview of the fundamental data types and formats used across Kissflow API parameters. ```APIDOC ## Fundamental Data Types These are the fundamental data types and formats used across different API parameters, including header, path, query, and request body parameters. Type | Description ---|--- String | A sequence of characters with Unicode support Integer | Signed 64-bit integral number Boolean | Represents a value of either **true** or **false** Date | A date formatted in ISO 8601 extended format: YYYY-MM-DD DateTime | Combined date and time formatted in ISO 8601 extended format: YYYY-MM-DDTHH:MM:SS±hh:mm For example, 2018-12-03T10:15:30+01:00 (Europe/Paris) ``` -------------------------------- ### Add an attachment Source: https://api.kissflow.com/ Uploads a file to a specific field of a dataset row. ```APIDOC ## POST Add an attachment ### Description Uploads a file to a specific field of a dataset row. ### Method POST ### Endpoint https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/attachment ### Headers - Content-Type: multipart/form-data - Accept: application/json - X-Access-Key-Id: (Required) - X-Access-Key-Secret: (Required) ### Path Variables - **account_id** (string) - Required - Kissflow Account ID. - **dataset_id** (string) - Required - The unique identifier for each dataset. - **row_id** (string) - Required - The unique identifier for each row in a dataset. - **field_id** (string) - Required - The Field ID is a unique identifier for each field. ### Request Body - **Attachment** (formdata) - Attach sample file in the body payload. ### Request Example ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/attachment' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="<"' \ --form '1="b"' \ --form '2="i"' \ --form '3="n"' \ --form '4="a"' \ --form '5="r"' \ --form '6="y"' \ --form '7=">"' ``` ### Response #### Success Response (200) - **response** (array) - Contains details of the uploaded attachment. - **Name** (string) - **_id** (string) - **PONumber** (string) - **TotalPrice** (string) - **_modified_by** (object) - **_id** (string) - **Name** (string) - **RequestedBy** (object) - **_id** (string) - **Name** (string) - **_modified_at** (dateTime) ### Response Example ```json { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "_modified_by": { "_id": "", "Name": "" }, "RequestedBy": { "_id": "", "Name": "" }, "_modified_at": "" } ] } ``` ``` -------------------------------- ### Rate Limiting and Payload Size Source: https://api.kissflow.com/ Information on API rate limits and payload size restrictions to ensure fair resource distribution and prevent abuse. ```APIDOC ## Rate limiting > 📘 To maintain a fair distribution of resources among API users and prevent abuse, we've set a threshold limit of 400 API calls per minute. This limit includes both programmatic and UI-based invocations. ### API Payload Size Limits The Kissflow API enforces a maximum payload size limit of 50 MB per request. Attempts to send payloads larger than this limit will result in an error. > **Note** : This limit applies to all API endpoints that accept request payloads. ``` -------------------------------- ### Base URL Structure Source: https://api.kissflow.com/ Details on the structure of the base URL used for constructing API endpoint URLs. ```APIDOC ## Base URL The base URL serves as the foundation for constructing the endpoint URL. ### Base URL structure The base URL is defined by protocols (schemes), host, and basePath and structured as:/// * Protocol: HTTP or HTTPS. * Host: Subdomain name and domain name. While the subdomain is unique to each Kissflow account, the domain name is kissflow.com or kissflow.eu. * Basepath: Consists of the service name and API version string. ## Resource URLs API requests are constructed using a dynamic base URL followed by the specific resource or collection URL. #### Example API endpoint: https://{subdomain}.kissflow.{region}/{service}/1/{path_params} ``` -------------------------------- ### Add an image file Source: https://api.kissflow.com/ Uploads an image file to a specific field of a dataset row. ```APIDOC ## POST Add image file ### Description Uploads an image file to a specific field of a dataset row. ### Method POST ### Endpoint https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/image ### Headers - Content-Type: multipart/form-data - Accept: application/json - X-Access-Key-Id: (Required) - X-Access-Key-Secret: (Required) ### Path Variables - **account_id** (string) - Required - Kissflow Account ID. - **dataset_id** (string) - Required - The unique identifier for each dataset. - **row_id** (string) - Required - The row ID is a unique identifier for each row. - **field_id** (string) - Required - The field ID is a unique identifier for each field. ### Request Body - **Add image** (formdata) - Add image in the body payload. ### Request Example ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/image' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="<"' \ --form '1="b"' \ --form '2="i"' \ --form '3="n"' \ --form '4="a"' \ --form '5="r"' \ --form '6="y"' \ --form '7=">"' ``` ### Response #### Success Response (200) - **response** (array) - Contains details of the uploaded image. - **Name** (string) - **_id** (string) - **PONumber** (string) - **TotalPrice** (string) - **_modified_by** (object) - **_id** (string) - **Name** (string) - **RequestedBy** (object) - **_id** (string) - **Name** (string) - **_modified_at** (dateTime) ### Response Example ```json { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "_modified_by": { "_id": "", "Name": "" }, "RequestedBy": { "_id": "", "Name": "" }, "_modified_at": "" } ] } ``` ``` -------------------------------- ### Upload Image using cURL Source: https://api.kissflow.com/ Use this cURL command to upload an image file to a specific field in a Kissflow dataset row. Ensure you replace placeholder values with your actual account, dataset, row, field IDs, and access keys. ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/image' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="<"' \ --form '1="b"' \ --form '2="i"' \ --form '3="n"' \ --form '4="a"' \ --form '5="r"' \ --form '6="y"' \ --form '7=">"' ``` -------------------------------- ### Upload Attachment using cURL Source: https://api.kissflow.com/ Use this cURL command to upload a file as an attachment to a specific field in a Kissflow dataset row. Ensure you replace placeholder values with your actual account, dataset, row, field IDs, and access keys. ```curl curl --location 'https://subdomain.kissflow.com/dataset/2/:account_id/:dataset_id/:row_id/:field_id/attachment' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'X-Access-Key-Id: ' \ --header 'X-Access-Key-Secret: ' \ --form '0="<"' \ --form '1="b"' \ --form '2="i"' \ --form '3="n"' \ --form '4="a"' \ --form '5="r"' \ --form '6="y"' \ --form '7=">"' ``` -------------------------------- ### Attachment Upload Response JSON Source: https://api.kissflow.com/ This is the expected JSON response structure after a successful attachment upload via the Kissflow API. ```json { "response": [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "_modified_by": { "_id": "", "Name": "" }, "RequestedBy": { "_id": "", "Name": "" }, "_modified_at": "" }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "_modified_by": { "_id": "", "Name": "" }, "RequestedBy": { "_id": "", "Name": "" }, "_modified_at": "" } ] } ``` -------------------------------- ### Bulk Update Dataset Records Response Body Source: https://api.kissflow.com/ The response body for a bulk update dataset records request will be a JSON array of the updated or created records. ```json [ { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } }, { "Name": "", "_id": "", "PONumber": "", "TotalPrice": "", "RequestedBy": { "_id": "", "Name": "" } } ] ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.