Introduction

Welcome to the Kotive API, and thank you for using Kotive!

Our API is build around REST, so all calls can be made using simple and predictable URLs!

All of our URLs start with https://webapp.kotive.com/api, and can be accessed with SSL only.

Authentication

var Kotive = require('kotive');

To authorise:

curl -u username:password https://webapp.kotive.com/api/login

var client = Kotive.Client('username', 'password');

Or alternatively

curl https://webapp.kotive.com/api/login       \
    -H 'Authorization: Basic <login details>'

var client = Kotive.Client('username', 'authToken');

Endpoint: GET /login

The Kotive API uses BASIC Auth to authenticate, and when you log in initially, it will provide you with an authToken that must be used with other requests. This authToken is sent instead of your password, and will expire when your session ends.

To get an authToken, you can sent a GET request to /login with your username and password specified in the -u tag, e.g.,

-u username:password

Or you could send a GET request to /login with the following header:

-H 'Authorization: Basic <login details>'

You must replace <login details> with your Base64 encoded username and password.

Example Response:

{
  "authToken": "3e2dfoxa58c243arabbitc17b9bb1bf7",
  "systemRoles": [{
    "id": 1,
    "label": "Account Owner"
  }, {
    "id": 2,
    "label": "User Administrator"
  }, {
    "id": 3,
    "label": "Maker"
  }],
  "userRoles": [{
    "userId": 14,
    "role": {
      "id": 1,
      "label": "Account Owner"
    },
    "groupId": 25
  }, {
    "userId": 14,
    "role": {
      "id": 2,
      "label": "User Administrator"
    },
    "groupId": 25
  }, {
    "userId": 14,
    "role": {
      "id": 3,
      "label": "Maker"
    },
    "groupId": 25
  }],
  "groupsIndex": [{
    "id": 24,
    "parentId": 1
  }, {
    "id": 24,
    "parentId": 245
  }],
  "user": {
    "email": "example@example.com",
    "username": "example@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "id": 14,
    "mobile": "",
    "password": "****"
  }
}

Great! You’ve successfully logged in! You’ll see that with the above login request, you get a JSON response that should look similar to that on the right.

We know it’s a little daunting at first, but here’s a breakdown of what’s included in the response:

Attribute	Description
authToken	This is the authToken that you may use instead of your password for making requests.
systemRoles	This is a list of all of the default roles associated with your account. Each entry consists of the ID of that group, and a human-friendly label. Custom roles will not be displayed here.
userRoles	This is a list of every role that has been assigned to you. Each entry contains your Person ID, a role object with the role ID and a description, and the ID of the group that you have that role in.
groupsIndex	This is a list of every group that you belong to. It shows you the group’s ID, as well as the ID of the parent group to which this group belongs.
user	Finally, this section provides you with information on your user account. It shows you your email address and username, your first and last names, your Person ID, your mobile phone number, and a hidden version of your password. Note that this will always show four stars, regardless of password length.

This information will come in handy later, but for now, we’re mostly just interested in the authToken attribute.

The authToken attribute can be used to replace the password in all further requests, and in both types of authentication. This is more secure than using your password, as if something ever goes wrong, we can easily revoke your authToken and issue you a new one.

To use it you would have:

-u username:authToken

Authorization: Basic <login details>

Where <login details> is made up of Base64 encoded username:authToken

Password reset

Example Request

curl https://webapp.kotive.com/api/user/resetpassword  \
    -X POST                                            \
    -H "Content-Type: application/json"                \
    -d '{"email": "example@example.com"}'

client.auth.passwordReset({email: "example@example.com"}, function (d) {
  // d is the response from the server
});

Example Response

OK

Endpoint: POST /user/resetpassword

You forgot your password? And you’ve already tried ‘1234’? Don’t worry, it happens to the best of us! Here’s how to recover it using the API:

Send a POST request to /user/resetpassword with "email": "<your email address>" as the payload.

That’s it! Now the user just has to follow the email prompts in their inbox to change their password.

If there is no user account associated with the email that you’ve entered, Kotive will send a new invitation email to that address, but will still return OK.

People

Get a list of people

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/people  \
    -H 'Authorization: Basic <login details>'

client.people.list(<group_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "people": [{
    "email": "example@example.com",
    "username": "example@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "id": 130,
    "mobile": "",
    "password": "****"
  }]
}

Endpoint: GET /group/<group_id>/people

Ever feel like you need a list of everybody that’s associated with your account? No? Well here’s how to do it anyway:

First of all you’ll need the group_id of the group, so that you can find out who is in that group. Getting this value should be pretty easy, as it will be nested inside of the groupsIndex part of the login response you got earlier!

Once you’ve got that value, all you have to do it submit a GET request to /group/<group_id>/people, and the reponse will contain the list of people you’re looking for.

Don’t forget to replace <group_id> with your actual Group ID, otherwise it won’t work.

Create a new person

Example Request

curl https://webapp.kotive.com/api/people      \
    -X POST                                    \
    -H "Content-Type: application/json"        \
    -H 'Authorization: Basic <login details>'  \
    -d '{"person": {"email": "<email>", "username": "<username>", "firstname": "<firstname>", "lastname": "<lastname>", "mobile": "<mobile>", "password": "<password>", "groupId": <groupId>}}'

client.people.create({email: '<email>', username: '<username>', firstname: '<firstname>', lastname: '<lastname>', mobile: '<mobile>', password: '<password>', groupId: <groupId>}}, function (d) {
  // d is the response from the server
});

Example Response

{
  "person": {
    "email": "johanna@example.com",
    "username": "johanna@example.com",
    "firstname": "Johanna",
    "lastname": "Doe",
    "id": 133,
    "mobile": "",
    "password": "****"
  }
}

Endpoint: POST /people

Has a new special someone come into your life? ;) Or is it just that time of year when your company has hired a whole load of newbies and wants you to add them to the system? Either way, here’s how to do it quickly and still get time to procrastinate!

To create a new person (not really), you must make a POST request to /people with all of the information about the new person:

Attribute	Description	Required
email	The email address of the person to add	Yes
username	The username is the same as the email address	Yes
firstname	The person’s first name	Yes
lastname	The person’s last name	Yes
mobile	The person’s mobile number	No
password	The person’s password	No
groupId	The ID of the group to add the new person to	Yes

If you wish to send an invitation email to the person after you have added them, simply follow the instructions on Password reset, as resetting the password of a user that doesn’t yet exist will sent them an invitation email.

Update a person

Currently, the only change you can make to somebody’s details is changing which roles have been assigned to them. Details on how to do this can be found in the ‘Assign a role to a person’ and 'Revoke a role from a person’ sections.

Roles

Get a person’s roles

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/personRoles?personId=<person_id>  \
    -H 'Authorization: Basic <login details>'

client.roles.get(<group_id>, <person_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "personRoles": [{
    "id": 319,
    "userId": 130,
    "roleId": 22,
    "groupId": 26
  }]
}

Endpoint: GET /group/<group_id>/personRoles?personID=<person_id>

Not sure what your boss actually does all day? Here’s a quick and easy way to find out using our API:

Again, you’ll first need the group_id of the group, otherwise we won’t know where to look. This is easy to get, as it is in the groupsIndex part of the login response from earlier!

In order to know who to query (apparently it is unethical to know everything about everybody and use it against them), we also need the Person ID of the person we want to query. This is obtained from the id attribute of the Get a list of people response. You simply look through that for the person that you’re curious about (a.k.a. your boss), and BAM, their Person ID is in the id attribute.

Now that you have these values, you simply insert them in the URL of a GET request to /group/<group_id>/personRoles?personID=<person_id>, and we’ll return a JSON string with a list of all of the roles that that person has!

Assign a role to a person

Example Request

curl https://webapp.kotive.com/api/personRoles  \
    -X POST                                     \
    -H 'Authorization: Basic <login details>'   \
    -H "Content-Type: application/json"         \
    -d '{"personRole":{"userId": <user_id>, "roleId": <role_id>, "groupId": <group_id>}}'

client.roles.assign({personRole: {userId: <user_id>, roleId: <role_id>, groupId: <group_id>}}, function (d) {
  // d is the response from the server
});

Example Response

{
  "personRole": {
    "id": 34,
    "userId": 10,
    "roleId": 2,
    "groupId": 24
  }
}

Endpoint: POST /personRoles

Did you leave somebody off the system again in your last minute panic? Well, before you have a complete emotional breakdown (it’s almost Friday!), here’s how to remedy the situation:

As per usual, you’ll need the group_id of the group to edit the person’s roles in, as well as the actual id of the person to update. The Group ID is fetched from the groupsIndex section of the response from your initial login request, and the Person ID can be found in the Get a list of people response - just choose the one that you need.

Once you have these values, simply submit a POST request to /personRoles with the information of the role you want to add in the following format as the payload:

{"personRole":{"userId": <user_id>,"roleId": <role_id>, "groupId": <group_id>}}

Replace the <user_id> attribute with the Person ID of the person to update, and do the same for <group_id>, but for groups. The <role_id> attribute is the role ID you want to give to the person, and must correlate to the ID of an existing role

Revoke a role from a person

Example Request

curl https://webapp.kotive.com/api/personRoles/<id>  \
    -X DELETE                                        \
    -H 'Authorization: Basic <login details>'

client.roles.revoke(<id>, function (d) {
  // d is the response from the server
});

Example Response

{

}

Endpoint: DELETE /personRoles/<role link id>

Did someone (gasp) complain about their work load? We know you don’t want to, but if HR is forcing you to relieve their stress by giving them less roles, here’s how to do it:

For this API call, all you’ll need is the unique role link ID of the role.

To get the unique role link ID, you will need to look at the response from Get a person’s roles. Find the roleId value that corresponds to the role that you want to revoke, and use the id attribute to send a DELETE request to /personRoles/<id>.

Taskflows

In Kotive, the terms process and taskflow, and activity and task are used interchangably.

Get a list of live taskflows

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/taskflowReports  \
    -H 'Authorization: Basic <login details>'

client.taskflow.list(<group_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "taskflowReports": [{
    "id": 79,
    "label": "My Average Taskflow"
  }, {
    "id": 76,
    "label": "My Awesome Taskflow"
  }]
}

Endpoint: GET /group/<group_id>/taskflowReports

Who knows what your group is up to? Probably doing something fun, like taking over the world or eating ice cream. Without you. If you’re really that desperate, here’s how to get a list of live taskflows for your group:

First of all you’ll need the group_id of the group, so that you can find out what taskflows are in your group. Getting this value should be pretty easy, as it will be nested inside of the groupsIndex part of the login response you got earlier!

Once you have your group_id, simply submit a GET request to /group/<group_id>/taskflowReports to get a list of live taskflows!

Start a new taskflow

Step 1: Get the taskflow template

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<taskflow_id>/blank  \
    -H 'Authorization: Basic <login details>'

client.taskflow.getTemplate(<group_id>, <taskflow_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "activity": {
    "phase": "new",
    "label": "A Taskflow",
    "id_process": 0,
    "publish": false,
    "id_t": 79,
    "order": 0,
    "status": "blank",
    "fields": [],
    "id_owning_process": -1,
    "kind": "form"
  },
  "childActivities": [{
    "phase": "new",
    "label": "Taskero numero twoero",
    "id_process": 0,
    "publish": false,
    "id_t": 862,
    "order": 0,
    "status": "blank",
    "fields": [{
      "pattern": "str[][]",
      "visible": true,
      "style": "{\"kind\":\"email\"}",
      "label": "Le Random Field",
      "readonly": false,
      "id": "-1_862_1015",
      "order": 0,
      "required": true,
      "value": ""
    }],
    "id_owning_process": -1,
    "kind": "form"
  }, {
    "phase": "new",
    "label": "Taskero numero uno",
    "id_process": 0,
    "publish": false,
    "id_t": 749,
    "order": 0,
    "status": "blank",
    "fields": [{
      "pattern": "str[][]",
      "visible": true,
      "style": "{\"kind\":\"text\"}",
      "label": "Nuclear Missile Launch Codes",
      "readonly": false,
      "id": "-1_749_1020",
      "order": 0,
      "required": true,
      "value": ""
    }],
    "id_owning_process": -1,
    "kind": "form"
  }]
}

Endpoint GET /group/<group_id>/process/<taskflow_id>/blank

When you want to start a new taskflow, you will want to know which tasks are available as part of the first step of the taskflow.

When you request a specific taskflow in Kotive, it will return information about the taskflow. This will include the first task(s) that can be completed, as well as the fields pertaining to them.

Before you can view information on a specific taskflow, you will need to obtain the <group_id> of the group to which the taskflow belongs, as well as the <taskflow_id> of the taskflow.

Send a GET request to /group/<group_id>/process/<taskflow_id>/blank. The response will contain the following attributes:

Attribute	Description
activity	This attribute provides information on the current taskflow. A breakdown of this attribute is available here.
childActivities	This attribute contains a list of all of the tasks that are available to be executed. A breakdown of this attribute is available here.

Activity model

Attribute	Description
id	The ID of the instance of the task (only available for existing task instances)
label	The task’s human-friendly label
kind	The type of task that this is (e.g. form, email, sms, github, slack, …)
order	The order that this activity is in, starting at 0
status	The status of the task. This will default to ‘blank’
phase	The current phase that this task is in. This will default to 'new’
publish	Whether or not the task has been published
id_process	The ID of instance of the taskflow which is currently associated with this task
id_t	The ID of the task template (from the Designer)
id_owning_process	This attribute allows you to attach processes to processes. For now this will always default to `-1`
fields	A list of the fields contained within this task.

Field model

Attribute	Description
id	The unique ID that we use to identify your task. This is a compound ID, combined using underscores: `<id_field_instance>` `<activity.id_t>` `<id_field_template>`
label	The human-friendly label of the field
order	The position of the field in the task, starting at 0
pattern	The way the type of data is stored by Kotive. Examples of this are: `str[][]` (for dates, dividers, email, headings, numbers, paragraphs, passwords, telephone numbers, text, text areas, times, and web addresses), `mse[Option1^Option2][]` (multiple selection, for checkboxes), `and sse[Option1^Option2][]` (single selection, for radiobuttons and dropdown lists)
style	The HTML style that our webapp uses to display the field
required	Whether or not the field is required
visible	Whether or not the field is visible
readonly	Whether or not the field is readonly
value	The current value of the field

Step 2: Start a taskflow instance

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process  \
    -X POST                                                  \
    -H 'Authorization: Basic <login details>'                \ 
    -H 'Content-Type: application/json'                      \
    -d '{"id_process":<id_process>,"id_t":<id_t>,"id_owning_process":<id_owning_process>,"fields":[]}'

client.taskflow.startInstance(<group_id>, {id_process: <id_process>, id_t: <id_t>, id_owning_process: <id_owning_process>, fields: []}, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "Taskero numero twoero",
  "id_process": 375,
  "publish": false,
  "id_t": 809,
  "order": 0,
  "status": "blank",
  "fields": [{
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"email\"}",
    "label": "Le Random Field",
    "readonly": false,
    "id": "-1_809_1135",
    "order": 0,
    "required": true,
    "value": ""
  }],
  "id_owning_process": -1,
  "kind": "form"
}, {
  "phase": "new",
  "label": "Taskero numero uno",
  "id_process": 375,
  "publish": false,
  "id_t": 889,
  "order": 0,
  "status": "blank",
  "fields": [{
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"number\"}",
    "label": "Nuclear Missile Launch Codes",
    "readonly": false,
    "id": "-1_889_1230",
    "order": 0,
    "required": true,
    "value": ""
  }, {
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"divider\"}",
    "label": "",
    "readonly": false,
    "id": "-1_889_1231",
    "order": 1,
    "required": false,
    "value": ""
  }, {
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"textarea\"}",
    "label": "Presidential Banking Details",
    "readonly": false,
    "id": "-1_889_1232",
    "order": 2,
    "required": false,
    "value": ""
  }],
  "id_owning_process": -1,
  "kind": "form"
}]

Endpoint: POST https://webapp.kotive.com/api/group/<group_id>/process

Great! Now that you’ve got the taskflow template, you need to start a taskflow instance in order to get the id_process. You will then use the id_process to link all of your task instances. Getting this is pretty simple!

First of all, you build a JSON payload with the following attributes:

Attribute	Description
id_process	The ID of instance of the taskflow which is currently associated with this task. Leave this `0` for now.
id_t	The ID of the task template (from the Designer).
id_owning_process	This attribute allows you to attach processes to processes. For now this will always default to `-1`.
fields	A list of fields to send along with this request. Leave this blank when starting a new taskflow.

Now that you’ve build your JSON string, use it to submit a POST request to /group/<group_id>/process. This will return the tasks which are available in the first step of the taskflow, and includes the id_process.

The id_process is needed for submitting tasks.

Submit a task

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<process_id>/activity  \
    -X POST                                                                        \
    -H 'Authorization: Basic <login details>'                                      \
    -H 'Content-Type: application/json'                                            \
    -d'{"id_process":<id_process>,"id_t":<id_t>,"id_owning_process":<id_owning_process>,"fields":[{"id":<id>,"value":<value>},{"id":<id>,"value":<value>}]}'

client.taskflow.submit(<group_id>, <process_id>, {id_process: <id_process>, id_t: <id_t>, id_owning_process: <id_owning_process>, fields: [{id:<id>, value: <value>}, {id: <id>, value: <value>}]}, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "A Form",
  "id_process": 386,
  "publish": false,
  "id_t": 798,
  "order": 2,
  "status": "blank",
  "fields": [{
    "pattern": "str[value][]",
    "visible": true,
    "style": "{\"kind\":\"text\"}",
    "label": "Field",
    "readonly": false,
    "id": "-1_798_8701",
    "order": 0,
    "required": false,
    "value": "value"
  }],
  "id_owning_process": -1,
  "kind": "form"
}]

Endpoint: POST /group/<group_id>/process/<process_id>/activity

Have your deadlines gotten to the point where you’re giving up on that intern and just doing everything yourself? That’s probably for the best, I’ve heard he uses Internet Explorer. If you really want to replace him entirely with one simple command, here’s how to do it! Disclaimer: this command will not bring you coffee.

In order to submit a task, you will yet again need the <group_id> and the <process_id>. Once you have these values, all you have to do is submit a POST request to /group/<group_id>/process/<process_id>/activity.

The payload of the POST request must contain certain information, outlined below:

Attribute	Description
id	The ID of the instance of the task (only available for existing task instances)
id_process	The ID of the instance of the taskflow which is currently associated with this task
id_t	The ID of the task template (from the Designer)
id_owning_process	This attribute allows you to attach processes to processes. For now this will always default to `-1`
fields	This is a list of the fields you want to update. For each entry in the list, you provide the `id` of the field you want to update, and the new `value` to put into that field.

The response obtained from this request may be:

the same task, if not all of the required fields were completed,
a list of the next task(s) in the taskflow,
an empty list, if no tasks are available.

Get the next task in a taskflow

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<process_id>/next  \
    -H 'Authorization: Basic <login details>'

client.taskflow.next(<group_id>, <process_id>, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "A Form",
  "id_process": 386,
  "publish": false,
  "id_t": 798,
  "order": 2,
  "status": "blank",
  "fields": [{
    "pattern": "str[value][]",
    "visible": true,
    "style": "{\"kind\":\"text\"}",
    "label": "Field",
    "readonly": false,
    "id": "-1_798_8701",
    "order": 0,
    "required": false,
    "value": "value"
  }],
  "id_owning_process": -1,
  "kind": "form"
}]

Endpoint: GET /group/<group_id>/process/<process_id>/next

CONTINUE WITH TASKFLOW

As in the previous request, you’ll need to obtain the <group_id> of the group to which the taskflow belongs, as well as the <process_id> of the taskflow instance.

Once you have those values, simply point a GET request to /group/<group_id>/process/<process_id>/next to get the next task(s) in the taskflow. Pretty straightforward, huh?

The attributes contained in the response are in the activity model.

Introduction

Authentication

Login

Password reset

People

Get a list of people

Create a new person

Update a person

Roles

Get a person’s roles

Assign a role to a person

Revoke a role from a person

Taskflows

Get a list of live taskflows

Start a new taskflow

Step 1: Get the taskflow template

Activity model

Field model

Step 2: Start a taskflow instance

Submit a task

Get the next task in a taskflow

CONTINUE WITH TASKFLOW