Introduction

K-API is a REST API which can be used by external programs, websites, or services to interact with a user's Act! database.

In order to get started developing with the K-API, your application must first authenticate with the web api application. This will provide you with a token which you will need to include in all subsequent api calls in a HTTP header named "Token". Certain endpoints do not require authentication such as Auth and System and therefore, do not require the token to be present in order to access them.

Please proceed to the Authentication section below for more details.

K-API only accepts data in the json format. Therefore, in addition to the Token header, please ensure all your API calls include the "Content-Type" header with a value of "application/json" unless otherwise instructed in the API Endpoint documentation.

Authentication

To authenticate, you will need to use the Auth endpoint. Provide your database name, username, and password as HTTP header parameters.
Sample request with the header names you are required to use is shown below:

Request:

Response:

{
    "Token": "4bc7ae451cad45e5b6a73d1398a721eb32a35437dfeb499b86e1bc30c0a2b810",
    "TokenExpiryTime": "2021-02-09T21:10:12.5070953-05:00"
}

If an authentication or a general error occurs while logging in, a json response similar to the one below will be returned instead. It is recommended you check for the HasError property when authenticating, and handle and display error details as needed if the value is true. Sample response is shown below

{
    "HasError": true,
    "ErrorDetails": "Username is required\r\nParameter name: Username",
    "ErrorType": "System.ArgumentException"
}

Note that for performance reasons, these error related properties will not be returned in the response if no error occurs. This is true for other properties in the K-API as well. If a property returns the default value, such as a bool property returns false, or a string returns null or a blank string, it will not be returned in the response. This is done to improve performance therefore, please engineer your application to expect that these values may not be present 100% of the time and to use default values if not returned in the response.

Working with the endpoint documentation

If you visit the API Endpoints page, each endpoint should include some information regarding the function of the endpoint, and each GET/POST/PATCH/DELETE action should include information regarding the function and the supported headers. In K-API, functions such as paging, sorting, filtering etc. are performed via headers therefore, it is important that you read and understand the endpoint documentation. Information regarding which headers a endpoint supports can be found in the "Additional Information" column. In the screenshot below, we can see the headers supported highlighted in red.

Most endpoints in K-API require parameters or return data in specific formats. These formats are based on specific object types which are identified in the API Endpoints page. For example, when getting data from the GET /api/Activities endpoint, the data returned contains a collection of an Activity object as shown below. If you click on the blue Activity hyperlink, you can view the details of what properties in will include and also the data types of those properties.

Paging

Paging can be performed in K-API in similar to how it is done using T-SQL. Paging is highly recommended when you expect to retrieve large amount of data. Not doing so will increase the memory and CPU usage on the server. Paging requires use of 3 headers. The Take and Skip can be used to indicate the page size and how many contacts to skip in the page. In addition to these headers, the list must be sorted in order to perform paging as required by SQL. Sorting can be performed by using either Sort or SortDesc headers. For more information on sorting, please see the Sorting section. In the example below, we get a list of Contacts in the database, 50 records at a time and sorting the list by Edit Date.

Sorting

When retrieving data from most endpoints, the list can be sorted by one of the columns. To sort a list in ascending order, use the Sort header. For descending order, SortDesc can be used. The value of the headers should be the field alias. In some endpoints, a slightly different column name is used for sorting or filtering. In those cases, the appropriate SQL Column name is listed in the API Endpoints documentation. The example below sorts the list of Contacts by Contact name field.

Filtering

Filtering can be performed by passing in a query in SQL format using the Filter header. Endpoints that support filtering will indicated that the Filter header is supported. The column names of filterable columns is usually the field alias. For example, when using the Contacts endpoint, you can pass in a filter such as CONTACT like '%john%' and this will show you the Contacts that contain the word "John" in their Contact name. For other endpoints, the column name might be different and will be indicated on the model documentation page. A sample filter is displayed below.