Introduction

Hitask is an online task and project management software. With Hitask you can share tasks and projects with your team, add multi-user comments, track time, attach files, produce reports and much more.

• RESTful. API is designed in accordance with REST patterns and is so called RESTful API.
• JSON. Hitask support JSON for serialization of data. Response data is returned as root element.

API Endpoint URL

API endpoint is https://hitask.com/api/{method} where {method} is the name of API method.

Authentication

This API is SSL/HTTPS only.

All methods require authentication. Authentication achieved through User.authenticate which returns session id. Your application have to provide the session id with every request. There are two ways of doing this:

• Cookie. If your application framework supports cookies automatically you don't have to do anything, cookie will be sent with every request.
• HTTP header parameter. Alternatively you can provide session id as "x-hi-session" header with every request.

Rate limiting

We only allow a certain number of requests per client per minute. If you exceed this limit you will have to wait before your next request is processed.

API Key

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: "

Make sure to replace your_key with your API key.

To access the API you need to have API Key. API Key is a unique identifier assigned to you. To get your Key simply go into your Hitask account settings page. You will be asked to provide the name of your integration/app. You are required to provide your API Key as a parameter for some methods, for example API Key is required when you authenticate user session: User.authenticate

Authorization: your_key

User

Operations related to current user's account: authenticate, sign up, etc.

Authenticate

{
    "api_key" : myapikey;
    login : john;
    password : XXXXXXXXX;
}

Will produce the response:

{
    id : 12345678;
    level : 300;
    "session_id" : "e0f93451-5ad6-4550-b991-efb0ce1e271b";
}

curl -d "login=test&password=testtest&api_key={key}" -X GET https://{host}/user/authenticate

Example response:

{"login_id":"test","account_type":"PERSONAL_FREE","level":0,"session_id":"192ba608-c47a-4862-b838-a4wf45ff6ed7","id":4321,"picture_hash":"4d5d22b3-d00a-4ceb-9608-c3ad243r4e88","email":"test@email.com"}

• GET /user/authenticate will authenticate user using user name and password

Input parameters:

• user name
• password

Response values:

• id: unique user id used to identify this user account
• level: account level
• session_id: session token

Sign out

End current session

• GET /user/logout Close user's session.

Input parameters: * session_id: session token

User Account information

Example response:

{
    businessId : 123,
    businessLevel : 100,
    email : "name@email.com",
    emailConfirmed : "name@email.com",
    id : 123,
    isOnline : 1,
    level : 0,
    login : "john",
    firstName : "Mick",
    lastName : "Johnson",
    pictureSource: 1000,
    pictureHash: "4b0c75c8-14cc-4d9b2-80aa-b49f5cf62daf"
}

• GET /user Get current user account information

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a user. This is an integer, but it is recommended to handle it as String to avoid limitations with the way JavaScript integers are expressed.
accountType	String	User's account type: TEAM_BASIC, TEAM_BUSINESS, PERSONAL_FREE, PERSONAL_PREMIUM
login	String	user login id
firstName	String	user's First Name
lastName	String	user's Last Name
emailConfirmed	String	Email address that was confirmed by the user. (By clicking confirmaiton link sent to this email address.)
email	String	Email address that user entered but not confirmed.
businessId	Integer	unique identifier of user's Team Business account, if applicable
businessLevel	Integer	Membership level of user in Business account: 1 - member, 2 - manager, 10 - administrator, 100 - owner
pictureHash	String	Unique avatar identifier that should be used in order to build user avatar URL
pictureSource	Integer	Type of user avatar: See below

Type of user avatar

• 0 Avatar is missing (only happens if generation failed)
• 1 Avatar is auto-generating (searching social sources or auto generating: only happens if user registered few seconds ago)
• 2 Auto generated (initials on background)
• 10 Google
• 11 Facebook
• 12 Gravatar
• 100 User uploaded
• 1000 Unknown

User avatar sizes

Available user avatar image pixel sizes are: 16, 20, 22, 24, 32, 40, 44, 48, 64, 80, 88, 96, 100, 128, 192, 200

Update User Account information

• POST /user/update Update current user account information

Input parameters:

• firstname: First Name
• lastname: Last Name
• email: e-mail address. If email address is different from previously stored, an email message with address confirmation will be sent
• loginId: user login id

Additional parameters:

• returnInfo: if true response will contain updated user info instead of response with operation status.

Update User Avatar

Example response:

{"hash":"4b0c75c8-14cc-49b2-80aa-b49f5cf62daf"}

• POST /user/picture Update current user avatar

Input parameters:

• picture: Picture data
• x: (Optional) X coordinate of top left corner of square that will be used to crop the picture (x, y and width must be specified to crop the picture)
• y: (Optional) Y coordinate of top left corner of square that will be used to crop the picture (x, y and width must be specified to crop the picture)
• width: (Optional) Width of square that will be used to crop the picture (x, y and width must be specified to crop the picture)

Restrictions:

• max picture size is 1MB
• allowed image formats: "gif", "jpeg", "jpg", "png"

Error codes:

• HTTP 400 and code 32: picture upload failed, retry required
• HTTP 400 and code 34: crop parameters are invalid
• HTTP 400 and code 6: uploaded data is not a valid picture
• HTTP 400 and code 5: picture format is not valid
• HTTP 400 and code 25: picture exceeded maximum allowed size

Response:

JSON object with one property "hash": unique picture identifier.

Delete User Avatar

• DELETE /user/picture Delete current user avatar

Input parameters:

• returninfo: (optional) if "true" then full account info will be returned as described in GET /user

Get User Preferences

• GET /v6/user/preferences Returns user preferences in old format(Json as string)
• GET /user/preferences Returns user preferences in new format(Json as object)

Example response (old format):

{
    "notify_app_item_deleted": "true",
    "notify_app_item_completed": "true",
    "ttstart": "06:00",
    "first_day_of_week": "1",
    "comment_order": "1",
    "notify_app": "true",
    "default_new_item_use_last": "true",
    "show_confirmation_complete": "true",
    "notify_app_item_tags": "true",
    "notify_web": "true",
    "default_sharing_permission_auto": "[{\"principal\":16686710,\"level\":100}]",
    "default_new_item_sharing_permission": "[{\"principal\":18556710,\"level\":100}]",
    "show_issue_sequence_id": "false",
    "notify_web_item_participant": "true",
    "desktopNotifyState": "0",
    "notify_email": "true",
    "time_zone": "Europe/Paris",
    "language": "en",
    "default_sharing_permission_last": "[{\"level\":100,\"principal\":\"18556710\"}]",
    "notify_web_item_attachment": "true",
    "main_assign_user": "186905",
    "notify_app_item_comment": "true",
    "notify_email_item_tags": "true",
    "enable_time_tracking": "false",
    "notify_app_item_participant": "true",
    "default_sharing_permission": "50",
    "notify_email_item_modify": "true",
    "notify_web_item_completed": "true",
    "notify_web_item_priority": "true",
    "default_shared_1": "false",
    "notify_web_item_comment": "true",
    "default_shared_0": "true",
    "time_format": "24",
    "notify_email_item_reminder": "true",
    "notify_email_item_priority": "true",
    "default_assign_user": "0",
    "sub_task_complete_affect_parent": "false",
    "notify_email_item_attachment": "true",
    "duplicate_with_files": "false",
    "notify_email_item_participant": "true",
    "daily_summary_email_6": "true",
    "daily_summary_email_7": "true",
    "daily_summary_email_4": "true",
    "daily_summary_email_5": "true",
    "daily_summary_email_2": "true",
    "daily_summary_email_3": "true",
    "daily_summary_email_1": "true",
    "bigCalendarMode": "month",
    "daily_summary_email_": "true",
    "override_parent_permission_with_last_used": "false",
    "notify_web_item_modify": "true",
    "notify_app_item_attachment": "true",
    "notify_email_item_comment": "true",
    "notify_web_item_tags": "true",
    "notify_email_item_completed": "true",
    "date_format": "d-m-y",
    "notify_email_item_deleted": "true",
    "taskfilter": "0",
    "notify_web_item_deleted": "true",
    "notify_app_item_priority": "true",
    "notify_app_item_assigned": "true",
    "notify_web_item_assigned": "true",
    "notify_email_item_assigned": "true",
    "default_shared": "false",
    "item.action.combobutton.last-used": "DELETE",
    "notify_app_item_modify": "true",
}

Example response (new format changes):

{
    "default_sharing_permission_auto": [
      {
        "principal": 16686710,
        "level": 100
      }
    ],
    "default_new_item_sharing_permission": [
      {
        "principal": 18556710,
        "level": 100
      }
    ],
    "default_sharing_permission_last": [
      {
        "level": 100,
        "principal": "18556710"
      }
    ]
}

Set User Preferences

• POST /user/preferences

Request body contain dictionary of key-value pairs

Example request body:

{
notify_app_item_deleted: "true"
}

Team

1. Get Team account information

• GET /business

Will produce the response:

{
    "domainName": "doman",
    "title": "Development Team",
    "licensesNumber": 15,
    "licensesUsed": 12,
    "storageQuota": 7500,
    "storageUsed": 157,
    "storageQuotaFormatted": "7.50GB",
    "storageUsedFormatted": "157MB",
    "expirationDate": "2016-10-17T00:00:00.000+00:00",
    "emailInbox": "2187b87d0bsds2dd9fe@hitask.com"}

Response

	Description
domainName	subdomain name e.g. comapny.hitask.com
title	Team name
licensesNumber	number of user licenses
licensesUsed	number of used user licenses
storageQuota	file storage space available (integer)
storageUsed	file storage space used (integer)
storageQuotaFormatted	file storage space available as humnan readable string
storageUsedFormatted	file storage space available as humnan readable string
expirationDate	Account expiration date for TRIAL or Next billing date for TEAM BUSINESS
emailInbox	Unique email address used to create tasks for team by email

Team members and team properties

2. Get list of team members

• GET /team

3. Invite to join team account

• POST /team/member

Parameters

Parameter	Type	Description
email	string	Valid email address. Required
name	string	Full name. First name and last name separated by space. e.g. "Firstname Lastname"

Response codes

HTTP code	API Error code	Description
200		Invited,added
400	5	bad request, email address invalid
412	16	Already a member, (this email address is already member of Team)
412	79	User already invited in this team
400	12	User licenses exceeded

4. Remove team member

Removes team member or invited user

• DELETE /team/member

Parameters

Parameter	Type	Description
id	integer	member user id

Response codes

HTTP code	API Error code	Description
200		member removed
404	1	member not found
400	4	"id" parameter is mandatory

5. Resend invitation

In case user did not receive email invitation use this method to re-send invitation again

• POST /team/member/resend

Parameters

Parameter	Type	Description
email	string	Valid email address. Required

Response codes

HTTP code	API Error code	Description
200		Invited,added
400	5	bad request, email address invalid
412	16	Already a member, (this email address is already member of Team)
400	12	User licenses exceeded

Item

Operations with items: tasks, events, projects, notes, files.

Field	Type	Example	Description
id	long	123000	Globally unique item Identifier
guid	String (UDID)	123456abcdef	Globally unique item Identifier used for public sharing
user_id	long	123000	user id of owner, user who created this item
title	String (256)	My Task	title
short_name	String (8)	APIDOCS	Short name of project. Accepted by projects only. Restrictions: 8 characters length maximum, latin letters and digits.
issue_id	String	APIDOCS-17	Unique reference identifier for tasks and projects.
completed	int	0	Indication if this item is completed
color	int	0	Color tag (index of predefined colors) used for items (tasks, events, notes, ..). Onde of these colors: [no color, '#FB7E6E', '#F8B957', '#F3DF5B', '#C2D95B', '#6CB4FF', '#CAA4DF', '#B8B8B8']
color_value	Strng	#5e93c3	Color value used for projects. Default: #5e93c3 One of these colors: ['#5e93c3', '#fc2f6a', '#fd9426', '#fecb2e', '#55ce2e', '#cb77df', '#a18460']
category	int	1	Category (or type) of item: 0:project 1: task 2:event 4: note 5:file
message	String (10000)	Hello	Item description text
parent	long	0	Unique id of parent item. Default: 0. 0 means item is not child of another item and not inside of project
recurring	int	0	0: not recurring, 1: daily, 2: weekly, 3: monthly, 4: yearly
assigneeId	long	0	Assignee, primary responsible person. User id of user whom item is assigned to
participants	comma separated list of user identifiers	322,413	array of user id for this item participants
start_date	Date	2012-03-15T19:00:00.000+10:00	Start date and time for this item. Default:null.
is_all_day	int	0	Indicator that this item is "all day" event. Only date without time should be used from start/end date field..
alerts	JSON array of JSON objects	See "Alerts" below
shared	int	0	0: Item is private. 1: item is shared, visile to team memebrs (Business account feature)
time_last_update	Date	2012-03-15T19:00:00.000+10:00	Timestamp when this item was last changed (updated).
time_create	Date	2012-03-15T19:00:00.000+10:00	Timestamp when this item was created.
starred	int	0	If item is marked as starred, 1 or 0
time_track	int	0	1/0 flag to specify if time tracking is enabled for htis item. Default:0.
time_est	float	0	Time estimated for this item, in hours. Used in time tracking calculations.Optional.
time_spent	float	0	Total time spent recorded for this item.
priority	int	20000	Arbitrary priority. 10000-19999:low, 20000-29999:normal, 30000:high. Default: 20000 (normal)
tags	comma separated list of tags	"work","home"	array or tags added to item
instances	array[item_instance]	[]	array of instances for recurring item. at PUT/POST requests this field is ignored by the server.
location	object	{"longitude":123.1234567,"latitude":-4.0987654321,"address":"qwe"}	Map that contains long/lat coordinates and address
unread	number or null	0	Item is "unread" for this user. It was created or modified by someone else
permissions	JSON array	See "Permissions" below

Alerts structure

    {
        "id":900,
        "timeType":4,
        "time":5,
        "timeSpecified":"2016-08-31T11:00:00.000+04:00",
        "repeat":2,
        "repeatInterval":5,
        "sound":true,
        "alert":true,
        "email":true,
        "push":true
    }

Field	Type	Example	Description
id	long	900	optional: if id is not specified then new alert will be created, or existing updated otherwise
timeType	long	4	mandatory; possible values: 1 - specified time, 2 - days before, 3 - hours before, 4 - minutes before
time	long	5	mandatory if timeType in [2, 3, 4]
timeSpecified	date	"2016-08-31T11:00:00.000+04:00"	mandatory if timeType=1, format is same as for start_date and end_date of item object
repeat	long	2	optional: how many times reminder should be repeated
repeatInterval	long	5	optional: repeat interval in minutes
sound	boolean	true	optional: play sound
alert	boolean	true	optional: display notification in desktop/browser version of application
email	boolean	true	optional: send email
push	boolean	true	optional: send push notification to mobile device

To Create/Update/Delete reminders:

[
    {"timeType":4,"time":0,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,
    "email":true,"push":true},
    {"timeType":4,"time":5,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,"email":true,
    "push":true},
    {"timeType":3,"time":1,"repeat":1,
    "repeatInterval":0,"sound":true,"alert":true,"email":true,
    "push":true},
    {"timeType":1,"timeSpecified":"2016-08-31T11:00:00.000+04:00",
    "repeat":1,"repeatInterval":0,"sound":true,"alert":true,
    "email":true,"push":true}
]

• Create: simply add new alert to array and put data to server
• Update: simply update existing alert in array (id must be specified in alert object) and put data to server
• Delete: simply remove alert from array and put data to server

Alert object description:

Permissions

Permission is defined by a level integer value.

Level	Description	Title displayed in client	Sub-title (description) displayed in client app
0/none	Not visible to user. Server does not return this item in user's items	Not visible
10	User can see item in list. Item sub-items and file attachments. Item history.	View
20	User can add comments to item	View and Comment	See in their lists, View details, Add comments
30	User can add attachments. Can add sub-items, If project- can create new items in project	Add sub-tasks and attachments , "Create tasks in project"
40	User can assign/reassign	"Assign"
50	User can Complete, Log time. Transition to another status (future)	Complete and Assign	Complete, reassign to another Team member, Attach documents, Add sub-tasks, Log time.
60	User can modify all properties (except Sharing permissions)	Modify	Modify item except its Sharing permissions
70	Can change sharing permissions (can add level 70 but not remove)	"Share with others"
80	User can archive item
100	User can delete item	Everything	Modify, Change sharing, Delete, Archive

Unread value

Unread	What it means	Relationship to item
0 or null	Item is read (default)
1	Comment added	User is participant or assignee or creator. Comment added by someone else
2	Modified, sub-item added	Assignee, participant, creator
3	New item	Assignee, participant, creator

1. Get array of items

• GET /item

This method will return array of all items: tasks, events, files including projects. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item.

[{
    "id": 3361634,
    "user_id": 184743,
    "title": "event 5724 1",
    "completed": false,
    "color": 0,
    "color_value": "#2AAEF5",
    "category": 2,
    "message": null,
    "parent": 0,
    "recurring": 0,
    "recurring_interval": 1,
    "recurring_end_date": "2017-08-26T15:56:46.820+04:00",
    "time_last_update": "2016-08-26T18:04:04.340+04:00",
    "time_create": "2016-08-26T18:04:04.340+04:00",
    "start_date": "2016-08-27T00:00:00.000+04:00",
    "end_date": null,
    "due_date": null,
    "is_all_day": true,
    "shared": true,
    "reminder_enabled": null,
    "reminder_time": null,
    "reminder_time_type": null,
    "starred": false,
    "time_track": false,
    "time_est": 0,
    "time_spent": 0,
    "priority": 21720,
    "last_comment_id": null,
    "last_comment": null,
    "last_comment_user_id": null,
    "last_comment_create_datetime": null,
    "guid": "9769a9f9-726c-4ec8-a920-be16193c26a6",
    "parentGuid": null,
    "assignee": 0,
    "tags": null,
    "version": 1,
    "instances": null,
    "participants": null,
    "publish_url": null,
    "location": null,
    "alerts": null,
    "unread": null,
    "short_name": null,
    "issue_id": "164",
    "permission": 100,
    "permissions": [{
      "level": 100,
      "principal": "184743"
    }],
    "previews": null,
    "last_transition_time": null,
    "last_transition_user": null
  }

1.2 Get delta update of items

• GET /item/since/{timestamp}

Returns list of items that were changed or added since specified date. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item. Deprecated. Use /item/delta/{delta} instead.

1.3 Get delta update of items

• GET /item/delta/{delta}

Returns list of items that were changed or added since specified delta. Delta is is a unix timestamp (in milliseconds) fetched from header X-Cursor. It returns X-Cursor HTTP header. Cursor is a unix timestamp (in milliseconds) of server response. Example: 1478802464. It equals to timestamp of latest modified returned item.

[{
  "id": 3361634,
  "changed": false
}, {
  "id": 3362490,
  "changed": false
}, {
  "id": 3362767,
  "changed": false
}, {
  "id": 3362336,
  "changed": false
}, {
  "id": 3362771,
  "user_id": 184743,
  "title": "delta api",
  "completed": false,
  "color": 0,
  "color_value": "#2AAEF5",
  "category": 1,
  "parent": 0,
  "recurring": 0,
  "recurring_interval": 1,
  "recurring_end_date": "2017-11-14T12:25:29.964+04:00",
  "time_last_update": "2016-11-14T13:36:57.539+04:00",
  "time_create": "2016-11-14T13:36:19.429+04:00",
  "shared": true,
  "starred": true,
  "time_track": false,
  "time_est": 0,
  "time_spent": 0,
  "priority": 21760,
  "guid": "2141ab89-48ee-47b0-878e-c9ad304397b4",
  "assignee": 0,
  "version": 2,
  "changed": true,
  "issue_id": "632",
  "permission": 100,
  "permissions": [{
    "level": 60,
    "principal": "184769"
  }, {
    "level": 60,
    "principal": "184775"
  }, {
    "level": 100,
    "principal": "184743"
  }]
}]

2. Create Item

• POST /item will create new item

Mandatory parameters:

Param	Type	Description
guid	uuid	Unique identifier
title	string	maximum 255 characters

Optional parameters:

Param	Type	Description
parentGuid	uuid	Unique identifier of parent item.

Example Post data:

title: Project title
message: Desription
category: 0
newProject: true
priority: 21010
user_id: 190150
color_value: #fc2f6a
short_name: PROJ
permissions: [{"principal":190150,"level":100}]
start_date: 2018-05-05T23:59:59.999+02:00
due_date: 2018-05-12T23:59:59.999+02:00
cascadeAcl: 1
permission: 100
doAdd: true
isSubItem: false
manytasks: false

2.1 Upload file

• POST /file/upload will upload file and create respective file item
• Request Content-Type should be multipart/form-data

Mandatory params:

Param	Type	Description
session_id	text	User session.
file	binary	Content of file to upload.

Optional params:

Param	Type	Description
parent_id	number	Parent item identifier.

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a file item.

3. Update Item

• PUT /item will update (modify) item

Mandatory parameters:

Param	Type	Description
guid	uuid	Unique identifier
title	string	maximum 255 characters

Optional parameters:

Param	Type	Description
parentGuid	uuid	Unique identifier of parent item.

Response codes for Create and Update

HTTP code	API Error code	Description
200		Created/updated
400	73	Unable to add {principal X} because project/parent item is not shared with {principal X}.
400	74	{principal X} permission can not be {modified/added/removed} because it will conflict with parent {permission X} permissions.
400	75	{user X} can not be {assignee/participant} because they don't have access to project {project name}.
400	76	Owner {owner name} is not allowed to change own permission.
400	77	Permission {principal X} downgrade to {permission X} is not allowed because parent has {permission Y} for this principal.
400	78	Cannot remove {assignee/participant} {user name} permission.
400	80	Short name already used.
400	104	One of the parameters is mandatory

4. Delete

• DELETE /item/{guid} will delete item

Parameters: * {guid}: unique identifier of item.

User performing delete request must have sufficient rights to delete this object

Possible HTTP return responses:

• 200 operation successful
• 404 item not found. It may be already deleted or not visible to current user.
• 403 not authorised

5. History

5.1 Retrieve item history including comments:

• GET /item/history?id={item id}

5.2 Add comment

• POST /item/comment will add a new comment to the item

Parameters: id: item id, message: comment body text

5.3 Delete comment

• DELETE /item/comment will delete comment

6. Archive

6.1 Archive item

Moves item to Archive

• POST /item/archive will archive item

Parameters: * id or guid: id or guid of item to archive.

User performing request must have sufficient rights to archive specified item.

Possible HTTP return responses:

• 200 operation successful
• 403 not authorised
• 404 item not found; it may be already archived or not visible to current user

6.2. Restore item from archive

• GET /archive/restore will restore item from archive

Parameters: * id or guid: id or guid of item to restore.

User performing request must have sufficient rights to restore specified item.

Possible HTTP return responses:

• 200 operation successful
• 403 not authorised
• 404 item not found
• 507 limit of items exceeded for current account

6.3. Restore copy of item from archive

• GET /archive/restorecopy will restore copy of item from archive

Parameters: * id or guid: id or guid of item which copy to restore.

User performing request must have sufficient rights to restore specified item.

Possible HTTP return responses:

• 200 operation successful
• 403 not authorised
• 404 item not found
• 507 limit of items exceeded for current account

7. Multiple items operations

7.1 Delete multiple items

• POST /item/deletemultiple will delete items

Parameters: * id: comma separated list of item identifiers (example: id=1,2,3).

User performing request must have sufficient rights to delete specified items. No error will be rised and item delete request simply ignored if user does not have rights to delete specific item.

Possible HTTP return responses:

• 200 operation successful
• 400 invalid format of list of identifiers

7.2 Archive multiple items

• POST /item/archivemultiple will archive multiple items

Parameters: * id: comma separated list of item identifiers (example: id=1,2,3).

User performing request must have sufficient rights to archive specified items. No error will be rised and item archive request simply ignored if user does not have rights to archive specific item.

Possible HTTP return responses:

• 200 operation successful
• 400 invalid format of list of identifiers

Tag

Operations with tags: add, remove, list tags

1. Get list of tags

Example response

[{"name":"privatetag","shared":false,"id":388730},{"name":"tag","shared":true,"id":388728},{"name":"тег","shared":true,"id":388729}]

• GET /tag will return list of tags

Mandatory params:

Param	Type	Description
session_id	text	User session.

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a tag.
name	text	Name of the tag.
shared	boolean	Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code	API Error code	Description
200		Returns array of tags.
400	4	API session is required.

2. Add tag

Example response

{"name":"new tag from api","shared":false,"id":388731}

• POST /tag

Mandatory params:

Param	Type	Description
session_id	text	User session.
name	text	Name of the new tag.
item_id	long	Identifer of item.

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a tag.
name	text	Name of the tag.
shared	boolean	Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code	API Error code	Description
200		Returns created tag.
400	4	Tag name is required.
400	4	Item ID is required.
404	1	Item not found.
403	3	No enough permissions to modify item.

3. Update tag

Example response

{"name":"update tag from api","shared":false,"id":388731}

• PUT /tag/{id}

Mandatory params:

Param	Type	Description
session_id	text	User session.
name	text	New name of the tag.
id	long	Identifer of tag (param is part of the URL).

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a tag.
name	text	Name of the tag.
shared	boolean	Indicates if tag linked to shared item or private item for current user.

Response codes

HTTP code	API Error code	Description
200		Returns updated tag.
400	4	Tag name is required.
404	1	Tag not found.
403	3	No enough permissions to modify tag because no enough permissions to modify respective item.

4. Delete

Example response

{"response_status":0}

• DELETE /tag/{id}

Mandatory params:

Param	Type	Description
id	long	Identifer of tag (param is part of the URL).

Response codes

HTTP code	API Error code	Description
200		Tag deleted.
404	1	Tag not found.
403	3	No enough permissions to delete shared tag.

Groups

Operations with user groups. Organize team and contacts into groups.

Get list of groups

Example response

[
{
id: "q9xsalg4tc7hrbaddh56fxg1ekuqrci39g8i2y7krmwa2qny8s5",
name: "Everyone",
code: "EVERYONE",
color: "#FFFFFF",
members: [
1866247,
1861630,
1866033,
1286619
],
type: 1
}
]

• GET /group will return list of user's groups and contacts

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier
name	String	Group name
type	int	Group special type. If =1 then this is "Everyone" group containing all team members.

Add Group

• POST /group

Only user level Administrator can create group

parameters:

• name: group name

Update group

• PUT /group

Update group. Only user level Administrator can update group

parameters:

• id
• name: group name
• code
• color

Delete Group

• DELETE /group

Only user level Administrator can create group. This does not delete contacts. only group is deleted.

parameter:

• group id

Add Contact to Group

• POST /group/{groupId}/contact{id}

Add contact to the group

Only user level Administrator can add contact to the group

Remove Contact from a Group

• DELETE /group/{groupId}/contact{id}

Remove contact form the group

Only user level Administrator can add remove contact form the group.

Contact

Operations with user's contacts: add, remove, list contacts

Get list of user's contacts

• GET /contact will return list of user's contacts

Parameters

Parameter	Type	Description
includeSelf	1 or 0	Include current user.

Example response

{
email: "user@email.com"
emailConfirmed: "user@email.com"
firstName: "John"
id: 123
isOnline: false
lastName: "Jackson"
level: 100
login: "john"
pictureHash: "267744510460b6ec63453483f725252"
subscription: "BOTH"
}

Response fields:

Field	Type	Description
id	long	Globally unique primary identifier for a contact.
accountType	String	User's account type: TEAM_BASIC, TEAM_BUSINESS, PERSONAL_FREE, PERSONAL_PREMIUM
login	String	user login id
firstName	String	user's First Name
lastName	String	user's Last Name
emailConfirmed	String	Email address that was confirmed by the user. (By clicking confirmaiton link sent to this email address.)
email	String	Email address that user entered but not confirmed. Do not send emails to this address as it may not be confirmed.
pictureHash	String	Unique address of user's avatar picture. To display the picture following URL composition should be used: [http|https]://htiask.com/avatar/[pictureHash].[pixel size].gif where pixel size is one of 16, 20, 22, 24, 32, 40, 44, 48, 64, 80, 88, 96, 100, 128, 192, 200
subscription	String	Designates if contact request is sent or receved or if relationship is established. Can be one of: FROM, TO, BOTH. BOTH means contact relationship is established. FROM means request from this contact is received. TO means request was sent and we're waiting for user to accept. SELF means this is the current user.

Add contact

• POST /contact

Delete

• DELETE /contact

Search

• GET /contact/search find contact by name or email

Invite

• GET /contact/invite Invite contact to create an account

Approve invitation

• GET /contact/approve Approve invitation/connection

Add contact to Business account

• GET /contact/addtobusiness will add contact as member of Business account

Remove contact from Business account

• GET /contact/removefrombusiness will add contact as member of Business account

Error handling

You need to check HTTP status in case there's an error. Basic rule is to check that code is not 200. If it's not 200 then expanded error code and error message will be in Json data.

When response statux is not 200 OK. The response contains Json date in format:

{
 "error_message" : "This is an error message";
 "response_status" : 1;
}

The API uses the following HTTP error codes:

Error Code	Meaning
400	Bad Request --
401	Unauthorized -- Your API key is wrong or unauthorized
403	Forbidden -- The requested is forbidden
404	Not Found -- The specified item could not be foun
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Also, API uses following response codes:

Response Code Name	Response Code	Description Template
OK	0	"Ok"
NOT_FOUND	1	"%s not found"
UNIQUE_USER_PARAMETER_VIOLATION	2	"User with given %s already exists"
NO_PERMISSIONS	3	"No enough permissions %s"
IS_MANDATORY	4	"%s is mandatory%s"
INVALID_DATA_FORMAT	5	"Invalid data format of %s"
INVALID_DATA	6	"%s is not valid %s"
SESSION_NOT_FOUND	7	"Session not found, please authenticate first"
INVALID_API_KEY	8	"Invalid API Key"
INVALID_JSON_VERSION	9	"API version must be %s or higher"
STALE_OBJECT	10	"You are trying to update old object, which was cnaged on %s"
BAD_TARGET_USER	11	"Error sending message to user with id=%s"
LICENSE_OVERUSE	12	"You have no enough licenses to add new user"
FILE_NOT_READY	13	"File is not ready"
CONTACT_SELF_ADD	14	"You can't add yourself to the contact list"
CONTACT_EXIST	15	"Contact already exists"
USER_ALREADY_IN_BUSINESS	16	"User %s already in a business group"
OPERATION_NOT_ALLOWED	17	"%s operation is not allowed"
NO_EMAIL	18	"No email provided for user"
EMAIL_NOT_VALIDATED	19	"Email is not confirmed: please confirm your email address"
LIMIT_EXCEED	20	"%s limit exceeded"
LOGIN_ID_TAKEN	21	"Login id is already taken"
EMAIL_ALREADY_REGISTERED	22	"Email is already registered"
CLIENT_UPGRADE_REQUIRED	23	"Client upgrade required"
PARTICIPANTS_ADDING_ERROR	24	"User %s couldn't be added as participant"
EXCEEDED_SIZE	25	"Maximum size for %s is %s"
PAYMENT_ERROR	30	"Payment error: %s"
PAYMENT_DATA_INVALID	31,"Payment data is not valid"
PICTURE_UPLOAD_ERROR	32	"Upload failed"
NOT_BUSINESS_USER	33	"You are not a business user"
INVALID_PICTURE_CROP_PARAMETERS	34	"Crop parameters are invalid"
INVALID_PICTURE_HASH	35	"Provided picture hash either does not exist or you are not allowed to modify this picture."
PASSWORD_NOT_MATCH	36	"Provided password does not match your current password"
BUSINESS_DOMAIN_NAME_USED	37	"This domain name is already in use"
REGISTER_INVALID_EMAIL_FORMAT	38	"Invalid data format of email"
REGISTER_INVALID_LOGIN_FORMAT	39	"Invalid data format of user name"
REGISTER_INVALID_NAME_FORMAT	40	"Invalid data format of first name or last name"
FREE_PROJECTS_LIMIT_EXCEEDED	41	"Free projects limit exceeded"
FREE_TASKS_LIMIT_EXCEEDED	42	"Free tasks limit exceeded"
API_KEY_ALREADY_EXISTS	43	"You already created the API key, please delete it before creating the new"
INVITATION_USED	45	"Invitation already used"
INVALID_JSON_BODY	46	"The JSON body you provided in request is invalid"
INVALID_RECURRING_INTERVAL	47	"Minimum recurring interval value is %d. Maximum recurring interval value is %d"
ACCOUNT_TERMINATED	48	"Sorry but your account was terminated"
UNSUPPORTED_EXTERNAL_PROVIDER_ID	49	"Such external social provider is not supported"
EXTERNAL_ACCOUNT_DETAILS_INVALID	50	"External account details are not full or invalid"
EXTERNAL_ACCOUNT_EMAIL_DOES_NOT_MATCH_INVITATION_EMAIL	51	"External account email must be equal to email used in this invitation"
EXTERNAL_SYNC_REFRESH_TOKEN_REQUIRED	52	"Refresh token is required for external synchronization because of its offline nature"
EXTERNAL_SYNC_EXTERNAL_ACCOUNT_REQUIRED	53	"You do not have required %s account linked"
INSUFFICIENT_API_KEY_PERMISSIONS	54	"The API key you provided has not enough permission in order to run requested command"
NOT_READY	55	"%s is not ready"
EXTERNAL_ACCOUNT_ALREADY_LINKED	56	"This %s account is already used %s"
EXTERNAL_ACCOUNT_TYPE_ALREADY_LINKED	57	"You already have external account of this type linked"
MIRROR_ITEM_MODIFICATION_FORBIDDEN	58	"You are not allowed to %s this item"
EXTERNAL_SYNC_IS_RUNNING	59	"External synchronization is being executed currently.%s"
UNKNOWN_PRODUCT_OR_PLAN	60	"Selected product plan and/or product is not supported"
UNKNOWN_PPAYMENT_PROCESSOR	61	"Could not process your payment using selected processor %s"
ALREADY_SUBSCRIBED	62	"You are already subscribed to this plan."
LICENSE_USAGE_GREATER_THAN_PLAN_LICENSES	63	"Current team license usage is greater than number of licenses of selected subscription plan."
ALREADY_PUBLISHED_PLAN	64	"Such subscription plan already published."
NO_PERMISSIONS_TO_MANAGE_SUBSCRIPTION	65	"Team account administrator %s is responsible for renewing the subscription."
GOOGLE_NOTIFICATIONS_OVERLOADED	66	"Google notifications processor overloaded: please try again in few seconds"
CUSTOM_API_KEY_USAGE_LIMIT_EXCEEDED	67	"You are performing too many API requests per second"
CANT_REMOVE_PLAN	68	"Plan can be removed only if it is unpublished and without customers."
ACCOUNT_EXPIRED	69	"Account subscription expired. Please visit http://%s to subscribe.")
EXTERNAL_ACCOUNT_CREDENTIALS_EXPIRED	70	"It appears that %s access token expired. Please visit Settings, remove external account and link it again with HiTask. Sorry for the inconvenience."
EXTERNAL_ERROR	71	"Error: %s."
TEAM_ACCOUNT_TERMINATED_ERROR	72	"Team account terminated."
UNABLE_TO_SHARE_BECAUSE_OF_PROJECT	73	"Unable to add %s because project/parent item is not shared with %s"
UNABLE_TO_ALTER_PERMISSION_OF_CHILD_TASK	74	"%s permission can not be %s because it will conflict with parent %s permissions."
UNABLE_TO_ASSIGN_OR_PARTICIPATE_BECAUSE_NO_PERMISSIONS	75	"%s can not be %s because they don't have access to project %s"
OWNER_CANT_CHANGE_OWN_PERMISSION	76	"Owner %s is not allowed to change own permission"
UNABLE_TO_DOWNGRADE_PERMISSION	77	"Permission '%s' downgrade to '%s' is not allowed because parent has '%s' for this principal"
UNABLE_TO_REMOVE_PERMISSION_OF_ASSIGNEE_OR_PARTICIPANT	78	"Cannot remove %s %s permission"
USER_ALREADY_INVITED_IN_THIS_TEAM	79	"User %s already invited in current team"
SHORT_NAME_ALREADY_USED	80	"Short name already used"
UNABLE_TO_PARSE_FILE	81	"Unable to parse the file"
PARSED_FILE_CONTAINS_NO_ENTRIES	82	"Parsed file contains 0 entries"
FILE_FORMAT_NOT_SUPPORTED	83	"File format is not supported"
INVALID_GOOGLE_AUTH_CODE	84	"%s is not valid google auth code%s"
FORBIDDEN_TO_ACCESS_AREA	85	"You are not allowed to access %s. Account upgrade required."
ENDPOINT_DEPRECATED	86	"Current endpoint deprecated since %s."
SCORE_LIMIT_REACHED	87	"\"%s\" daily limit reached."
INVALID_PICTURE_MINIMUM_EDGE_LENGTH	88	"Minimum length for each edge of the picture is %spx"
INTERNAL_ERROR	100	"Internal error"
NOT_VALID_PREFERENCES	102	"Not valid preferences"
ONE_OF_IS_MANDATORY	104	One of the parameters %s is mandatory