REST API Points

How to set up REST APIs to create, update, and submit requests

Mayakrishnan Ramar avatar
Written by Mayakrishnan Ramar
Updated over a week ago

KiSSFLOW provides some REST endpoints through which you can programmatically create, update, and submit requests. KiSSFLOW endpoints support JSON responses and will communicate the successful completion of an API request.

In order to start using your APIs you need to know your API key and account name. KiSSFLOW is RESTful. There is a clear endpoint for each of the separate operations that need to be performed. However, the approach to call these endpoints is the same. You need to make an HTTP request on the endpoint using the particular method (GET by default unless otherwise mentioned). In addition to the required payload, you have to pass your API key in the header of every request.

In the below curl example we will show you how to check if your API calls are working:

curl -H "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/verify

Response:

{
  success: "All O.K."
}

List Process:

GET https://<your_account_id>.appspot.com/api/1/process

Use the List Process endpoint to list all the active process running in your account. The Response for this endpoint will be a JSON object which contains the list of created processes along with the Unique ID Associated with each process.

curl -H "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/process

Response:

[
    {
        Id: "Travel_Claim"
        Name: "Travel Claim"
        Description: "To claim travel expenses"
    },
    {
        Id: "Quotation"
        Name: "Quotation"
        Description: "Online Quotation"
    },
    {
        Id: "Invoice"
        Name: "Invoice"
        Description: "Create and manage Invoice"
    }
]

Create Request:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/create

Use the Create Request endpoint to create a new request and save it in the Draft of the special integration user. The response for this Endpoint will be a JSON object that contains the values that were stored because of the API call along with the Unique ID Associated with the Request Object.

The payload of the request body should contain the values that need to be stored for the request.

Let’s consider a Travel Claim process for an example:

curl -H "api_key:<your_api_key>" -X POST --data-urlencode "PlaceVisited=Singapore" --data-urlencode "Amount=10000" https://<your_account_id>.appspot.com/api/1/Travel Claim/create  

Response:

{
    PlaceVisited: "Singapore"
    Amount: 10000
    Id: "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0428"
    Subject: "Request for Singapore"
}

Create & Submit Requests:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/submit

Use the Create and Submit Request endpoint to create a new Request and immediately submit it into the approval flow. The Response for this endpoint will be a JSON object which contains the values that were stored because of the API call along with the Unique ID associated with the Request object.

The payload of the request body should contain the values that need to be stored for the request.

For example:

curl -H "api_key:<your_api_key>" -X POST --data-urlencode "PlaceVisited=Singapore" --data-urlencode "Amount=10000" https://<your_account_id>.appspot.com/api/1/Travel Claim/submit

Response:

{
    Id: "TravelClaim001",
    Subject: "Request for Singapore"
}

Update Request:

PUT https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/update

Use the Update Request endpoint to update an existing request with new values. The Response for this endpoint will be a JSON object which contains the values that were stored because of the API call along with the Unique ID associated with the Request object.

The payload of the request body should contain the values that need to be stored for the request.

For example, here is how to update the travel amount from 10,000 to 14,000:

curl -H "api_key:<your_api_key>" -X PUT --data-urlencode "Amount=14000" https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/update

Response:

{
  "PlaceVisited": "Singapore",
  "Amount": 14000,
  "Id": "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0428",
  "Subject": "Request for Singapore"
}

Delete Request:

DELETE https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/delete

Use the Delete Request endpoint to delete an existing request. The Response for this endpoint will be a JSON object which contains the success/error message. For example:

curl -H "api_key:<your_api_key>" -X DELETE https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/delete

Response:

{
    success: "Successfully deleted"
}

Approve Request:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/approve

Use the Approve Request endpoint to approve an existing request. The Response for this endpoint will be a JSON object which contains the Unique ID associated with the Request Object.

Here is an example:

curl -H "api_key:<your_api_key>" -X POST https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/approve

Response:

{
    Id: "TravelClaim001",
    Subject: "Request for Singapore"
}

Reject Request:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/reject

Use the Reject Request endpoint to reject an existing request. The Response for this endpoint will be a JSON object which contains the Unique ID associated with the Request Object.

For this API, Comment is a mandatory parameter. For example:

curl -H "api_key:<your_api_key>" -X POST --data-urlencode "Comment=travel date is wrong" https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/reject

Response:

{
    Id: "TravelClaim001",
    Subject: "Request for Singapore"
}

Provide Input (Done) Request:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/done

Use the Done Request endpoint to complete a provide input step. The Response for this endpoint will be a JSON object which contains the Unique ID associated with the Request Object.

Example:

curl -H "api_key:<your_api_key>" -X POST --data-urlencode "Amount=15000" https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/done

Response:

{
    Id: "TravelClaim001",
    Subject: "Request for Singapore"
}

Get Clarity:

POST https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/clarify

Use the Get Clarity endpoint to perform a clarification seek action.  Two parameters are mandatory in the body of the request; Comment and GetClarityFrom. The response for this endpoint will be a JSON object.

Example:

curl -H "api_key:<your_api_key>" -X POST --data-urlencode "Comment=When+do+you+want+It&GetClarityFrom=[email protected]" https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/clarify

Response:

{
    Id: "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0428"
    Subject: "Request for Singapore"
}

Read Request:

GET https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/read

Use the Read Request endpoint to read an existing request. The Response for this endpoint will be a JSON object which represents the values in the entity with the associated Unique ID.

Here is an example for reading the request for Singapore Travel Claim process:

curl -H "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/Travel Claim/Request for Singapore/read

Response:

{
    PlaceVisited: "Singapore"
    Amount: 14000
    Id: "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0428"
    Subject: "Request for Singapore"
}

List Requests:

GET https://<your_account_id>.appspot.com/api/1/<process_name>/list/p<page_number>/<page_size>

Use the List Request endpoint to list all existing requests. The Response for this endpoint will be a JSON object which contains the list of entities with the associated Unique ID.

If you want to filter the item based on task (or process step), do the following:

https://<your_account_id>.appspot.com/api/1/<process_name>/list/<process_step>/p<page_number>/<page_size>

An example for listing a Travel Claim process:

curl - H  "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/Travel Claim/list/p1/50
curl - H  "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/Travel Claim/list/Manager Approval/p2/50

Response:

[
  {
    "PlaceVisited": "Singapore",
    "Amout": 14000,
    "Id": "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0428",
    "Subject": "Request for Singapore"
  },
  {
    "PlaceVisited": "Malaysia",
    "Amout": 12000,
    "Id": "Sh2a6b8c51_84e7_11e3_bdd0_ddc2c98b0429",
    "Subject": "Request for Malaysia"
  }
]

Progress Details for a Request:

This API helps to get workflow progress details for a request with individual comments on every step.

GET https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/progress
curl -H "api_key:<your_api_key>" -X GET https://<your_account_id>.appspot.com/api/1/<process_name>/<request_subject or request_id>/progress

Response:

{
    "Id": "Process001",
    "Process Name": "Leave Req",
    "Subject": "Request for Leave 01/02/2015 - 03/02/2015",
    "Completed Percentage": 20,
    "Steps": [
        {
            "Name": "Initiated",
            "Type": "Draft",
            "Id": "Step001",
            "Status": "Completed",
            "Completed By": "[email protected]",
            "Completed At": "2015-08-25 12:34:39"
        },
        {
            "Name": "Manager Approval",
            "Type": "Approval",
             "Id": "Step002",
            "SLA": 32,
            "Status": "Completed",
            "Time Taken": 0.03,
            "Completed By": "[email protected]",
            "Completed At": "2015-08-25 12:34:39"
        },
        {
            "Name": "Sr.Manager Approval",
            "Type": "Approval",
             "Id": "Step003",
             "Status": "In Progress",
            "SLA": 32,
             "ETA": "2015-08-26 20:34:48",
             "Queried To": "[email protected]",
             "Assigned To": [
                 "[email protected]",
                 "[email protected]"
             ],
            "Comments":[
                {
                    "Comment": "Leave Approved",
                    "Commented At": "2015-08-25 18:12:33",
                    "Commened By": "[email protected]"
                }
            ]
        },
        {
            "Id": "Step004",
            "Type": "Parallel",
            "Branches": [
                {
                    "Id": "Branch001",
                    "Completed Percentage": 0,
                    "Steps":[
                        {},{} //same as above mentioned steps, Step002
                    ]
                },
                {
                    "Id": "Branch002",
                    "Completed Percentage": 0,
                    "Steps":[
                        {},{} //same as above mentioned steps, Step002
                    ]
                }
            ]
        }
     ]
}


Note:
If you have to perform a REST endpoint on behalf of other users, you need to add “email_id” as part of request header in addition with “api_key.” This is an optional parameter. If omitted, the operation will be performed by default system user named “integrationuser@.”

Did this answer your question?