API Introduction

OneDesk provides Representational State Transfer (REST) web service. To use a REST API, your can make an HTTP request and parse the response. The request and response support JSON.

URI Structures

The URIs in OneDesk have the following structures: https://onedesk.com/rest/api-version/api-name/resource-name api-version: The current api-version is 2.0

Login API

Login

POST https://app.onedesk.com/rest/2.0/login/loginUser
You should either send the email and the password OR the cookie

Request fields

Path Type Description

email

String

Email of the user

password

String

password of the user

cookie

String

Login cookie

Response fields

Path Type Description

code

String

the result of the API operation

data.name

String

user name

data.authenticationToken

String

Authentication token

data.cookie

String

Cookie to be used next time the user want to login

data.userId

Number

User ID

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/login/loginUser' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "cookie" : "",
  "email" : "john.smith@acme.com",
  "password" : "XXXXXXXXXX"
}'

Example request

POST /rest/2.0/login/loginUser HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 83

{
  "cookie" : "",
  "email" : "john.smith@acme.com",
  "password" : "XXXXXXXXXX"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 184

{
  "code" : "SUCCESS",
  "data" : {
    "name" : "John Smith",
    "authenticationToken" : "00000000000",
    "cookie" : "4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
    "userId" : 1
  }
}

Logout

GET https://app.onedesk.com/rest/2.0/login/logoutUser

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/login/logoutUser?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/login/logoutUser?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41

{
  "code" : "SUCCESS",
  "data" : null
}

Organization API

Get organization basic information

GET https://app.onedesk.com/rest/2.0/organization/getOrgInfo

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.statuses.[].id

Number

Id of the lifecycleStatus

data.statuses.[].name

String

Name of the lifecycleStatus

data.statuses.[].iconStyleName

String

icon style of the lifecycleStatus

data.statuses.[].iconColor

Number

Icon color of the lifecycleStatus

data.statuses.[].appliedProperty

String

Applied property of the lifecycleStatus

data.itemTypes.[].name

String

Name of the item type

data.itemTypes.[].iconStyleName

String

icon style of the item type

data.itemTypes.[].iconColor

Number

Icon color of the item type

data.itemTypes.[].visible

Boolean

visibility of the item type

data.itemTypes.[].itemType

String

item type

data.userTypes.[].name

String

Name of the user type

data.userTypes.[].iconStyleName

String

icon style of the user type

data.userTypes.[].iconColor

Number

Icon color of the user type

data.userTypes.[].userType

String

user type

data.applicationVisibility.viewProjectManagement

Boolean

view project management

data.applicationVisibility.viewProductManagement

Boolean

view product management

data.applicationVisibility.viewFeedbackManagement

Boolean

view feedback management

data.applicationVisibility.viewWork

Boolean

view work

data.applicationVisibility.viewDashboard

Boolean

view dashboard

data.applicationVisibility.viewAllItems

Boolean

view all items

data.policy.defaultThreadVisibilityType

String

default thread visibility type

data.organizationProfile.organizationUri

String

organization Uri

data.organizationProfile.dateFormat

Date

organization dateFormat

data.organizationProfile.organizationName

String

organization name

data.applicationVisibility.viewUsers

Boolean

view users

data.applicationVisibility.viewCustomers

Boolean

view customers

data.applicationVisibility.viewContainers

Boolean

view containers

data.applicationVisibility.viewActivities

Boolean

view activities & Discussions

data.applicationVisibility.viewCommunication

Boolean

view communication

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/organization/getOrgInfo?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/organization/getOrgInfo?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1687

{
  "code" : "SUCCESS",
  "data" : {
    "statuses" : [ {
      "id" : 6544131,
      "name" : "In Progress",
      "iconStyleName" : "in_progress_icon_style",
      "iconColor" : 25651,
      "appliedProperty" : "TASK_TYPE_1_LCS"
    }, {
      "id" : 6544132,
      "name" : "Finished",
      "iconStyleName" : "finished_icon_style",
      "iconColor" : 21526,
      "appliedProperty" : "TASK_TYPE_1_LCS"
    } ],
    "itemTypes" : [ {
      "itemType" : "TASK_TYPE_1",
      "name" : "Task",
      "iconStyleName" : "task_icon_style",
      "iconColor" : 21526,
      "visible" : true
    }, {
      "itemType" : "TASK_TYPE_2",
      "name" : "Issue",
      "iconStyleName" : "issue_icon_style",
      "iconColor" : 987426,
      "visible" : true
    } ],
    "userTypes" : [ {
      "userType" : "USER_TYPE_1",
      "name" : "User",
      "iconStyleName" : "user_icon_style",
      "iconColor" : 845152
    }, {
      "userType" : "USER_TYPE_2",
      "name" : "VIP user",
      "iconStyleName" : "vip_user_icon_style",
      "iconColor" : 21654
    } ],
    "applicationVisibility" : {
      "viewAllItems" : true,
      "viewProjectManagement" : true,
      "viewProductManagement" : true,
      "viewFeedbackManagement" : true,
      "viewWork" : false,
      "viewDashboard" : false,
      "viewUsers" : true,
      "viewCustomers" : true,
      "viewContainers" : true,
      "viewActivities" : true,
      "viewCommunication" : true
    },
    "policy" : {
      "defaultThreadVisibilityType" : "PUBLIC_DISCUSSION_POST"
    },
    "organizationProfile" : {
      "dateFormat" : "Date",
      "organizationName" : "onedesk",
      "organizationUri" : "onedesk"
    }
  }
}

Space API

Get space by id

POST https://app.onedesk.com/rest/2.0/space/getItemById

Request fields

Path Type Description

authenticationToken

String

authentication token

id

Number

ID of the space

Response fields

Path Type Description

code

String

the result of the API operation

data

Object

space details (see response example for details)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/space/getItemById' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "id" : 333
}'

Example request

POST /rest/2.0/space/getItemById HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 57

{
  "authenticationToken" : "00000000000",
  "id" : 333
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 257

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 333,
    "name" : "space 1",
    "description" : "...",
    "type" : "SPACE_TYPE_0",
    "created" : "2019-10-18T11:09:08:548+00:00",
    "parentIds" : [ 444, null ],
    "customFields" : {
      "cf1" : "cf1 value"
    }
  }
}

Create space

POST https://app.onedesk.com/rest/2.0/space/create

Request fields

Path Type Description

authenticationToken

String

authentication token

name

String

name of the space

containerType

String

type of the space (SPACE_TYPE_0 .. SPACE_TYPE_9)

description

String

description of the space

parentIds

Array

array of parent/portfolio IDs

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

Id of the created space

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/space/create' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "name" : "space 1",
  "authenticationToken" : "00000000000",
  "containerType" : "SPACE_TYPE_0",
  "description" : "description 1",
  "parentIds" : [ 345 ]
}'

Example request

POST /rest/2.0/space/create HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 161

{
  "name" : "space 1",
  "authenticationToken" : "00000000000",
  "containerType" : "SPACE_TYPE_0",
  "description" : "description 1",
  "parentIds" : [ 345 ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 56

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 33
  }
}

Search spaces

POST https://app.onedesk.com/rest/2.0/space/search

Request fields

Path Type Description

authenticationToken

String

authentication token

itemIds

Array

array of space IDs to filter

filters

Array

array of filters

filters.[].propertyName

String

name of the property to filter ([custom field name], creatorId, name)

filters.[].operation

String

operation of the filter (EQ, NE, NOT_EMPTY)

filters.[].value

String

the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS)

filters.[].isCustomField

Boolean

set this to true for custom field/property filter

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

total number of IDs

data.items

Array

array of IDs of the spaces

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/space/search' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "name",
    "operation" : "EQ",
    "value" : "space 1",
    "isCustomField" : false
  }, {
    "propertyName" : "Custom Field 3",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  } ]
}'

Example request

POST /rest/2.0/space/search HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 315

{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "name",
    "operation" : "EQ",
    "value" : "space 1",
    "isCustomField" : false
  }, {
    "propertyName" : "Custom Field 3",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  } ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ 3, 5 ],
    "total" : 2
  }
}

Portfolio API

Get portfolio by id

POST https://app.onedesk.com/rest/2.0/portfolio/getItemById

Request fields

Path Type Description

authenticationToken

String

authentication token

id

Number

ID of the portfolio

Response fields

Path Type Description

code

String

the result of the API operation

data

Object

portfolio details (see response example for details)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/portfolio/getItemById' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "id" : 444
}'

Example request

POST /rest/2.0/portfolio/getItemById HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 57

{
  "authenticationToken" : "00000000000",
  "id" : 444
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 182

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 444,
    "name" : "portfolio 1",
    "type" : "PORTFOLIO_TYPE_0",
    "created" : "2019-10-18T11:09:08:237+00:00",
    "parentIds" : [ 555, null ]
  }
}

Search portfolios

POST https://app.onedesk.com/rest/2.0/portfolio/search

Request fields

Path Type Description

authenticationToken

String

authentication token

itemIds

Array

array of portfolio IDs to filter

filters

Array

array of filters

filters.[].propertyName

String

name of the property to filter (name)

filters.[].operation

String

operation of the filter (EQ, NE)

filters.[].value

String

the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS)

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

total number of IDs

data.items

Array

array of IDs of the portfolios

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/portfolio/search' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "name",
    "operation" : "EQ",
    "value" : "portfolio 1",
    "isCustomField" : false
  } ]
}'

Example request

POST /rest/2.0/portfolio/search HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 197

{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "name",
    "operation" : "EQ",
    "value" : "portfolio 1",
    "isCustomField" : false
  } ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 80

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ 50 ],
    "total" : 1
  }
}

User API

Create user

POST https://app.onedesk.com/rest/2.0/user/create

Request fields

Path Type Description

authenticationToken

String

Authentication token

email

String

The new user email

firstName

String

The first name

lastName

String

The last name

type

String

The user type (USER_TYPE_1 .. USER_TYPE_10, CUSTOMER_TYPE_1 .. CUSTOMER_TYPE_10)

teamId

Number

The ID of the team

registrationStatus

String

The registration status (INVITATION_SENT)

isAdministrator

Boolean

true if the new user should be an administrator

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

Id of the newly created user

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/create' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "email" : "john.smith@acme.com",
  "firstName" : "john",
  "lastName" : "smith",
  "type" : "USER_TYPE_1",
  "teamId" : 1,
  "isAdministrator" : false,
  "registrationStatus" : "REGISTERED"
}'

Example request

POST /rest/2.0/user/create HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 236

{
  "authenticationToken" : "00000000000",
  "email" : "john.smith@acme.com",
  "firstName" : "john",
  "lastName" : "smith",
  "type" : "USER_TYPE_1",
  "teamId" : 1,
  "isAdministrator" : false,
  "registrationStatus" : "REGISTERED"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 945621
  }
}

Get users

POST https://app.onedesk.com/rest/2.0/user/get

Request fields

Path Type Description

authenticationToken

String

Authentication token

usersIds

Array

The IDs of users

usersEmails

Array

The emails of users (if user IDs are not specified)

Response fields

Path Type Description

code

String

the result of the API operation

data

Array

list of users (see response example for details)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/get' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "usersIds" : [ 123547, 851651 ],
  "usersEmails" : [ ]
}'

Example request

POST /rest/2.0/user/get HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 101

{
  "authenticationToken" : "00000000000",
  "usersIds" : [ 123547, 851651 ],
  "usersEmails" : [ ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1837

{
  "code" : "SUCCESS",
  "data" : [ {
    "id" : 851651,
    "organizationId" : 1,
    "loginName" : null,
    "category" : null,
    "type" : "USER_TYPE_1",
    "activationStatus" : null,
    "registrationStatus" : null,
    "lastInvitation" : null,
    "customFields" : [ ],
    "externalId" : null,
    "calendarUrl" : null,
    "profile" : {
      "id" : null,
      "email" : null,
      "firstName" : "John",
      "lastName" : "Smith",
      "phoneWork" : null,
      "photoUrl" : null,
      "title" : null,
      "pictureKey" : "k1",
      "color" : "#FF0000"
    },
    "address" : null,
    "userCalendarOptions" : null,
    "created" : null,
    "authorId" : null,
    "priority" : null,
    "organizationalId" : null,
    "userWorkTimer" : null,
    "pushNotificationsRegistrationId" : null,
    "destructorId" : null,
    "deleteDate" : null,
    "userConversationsSettings" : null,
    "displayName" : "John Smith"
  }, {
    "id" : 123547,
    "organizationId" : 1,
    "loginName" : null,
    "category" : null,
    "type" : "USER_TYPE_2",
    "activationStatus" : null,
    "registrationStatus" : null,
    "lastInvitation" : null,
    "customFields" : [ ],
    "externalId" : null,
    "calendarUrl" : null,
    "profile" : {
      "id" : null,
      "email" : null,
      "firstName" : "Derek",
      "lastName" : "Gold",
      "phoneWork" : null,
      "photoUrl" : null,
      "title" : null,
      "pictureKey" : "k2",
      "color" : "#FF0000"
    },
    "address" : null,
    "userCalendarOptions" : null,
    "created" : null,
    "authorId" : null,
    "priority" : null,
    "organizationalId" : null,
    "userWorkTimer" : null,
    "pushNotificationsRegistrationId" : null,
    "destructorId" : null,
    "deleteDate" : null,
    "userConversationsSettings" : null,
    "displayName" : "Derek Gold"
  } ]
}

Load user work timer

GET https://app.onedesk.com/rest/2.0/user/userWorkTimer

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

the user id

data.itemId

Number

the work item id

data.startDate

Date

the start date of this work timer

data.amountOfWork

Number

The amount of work in hours for this work timer

data.startCurrentTimer

Date

the start date of the current progress of the work timer

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/userWorkTimer?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/user/userWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 651321,
    "itemId" : 213547,
    "startDate" : "2019-10-18T11:09:08:687+00:00",
    "amountOfWork" : 6.0,
    "startCurrentTimer" : "2019-10-18T11:09:08:687+00:00"
  }
}

Start work timer

GET https://app.onedesk.com/rest/2.0/user/startWorkTimer

Request parameters

Parameter Description

token

authentication token

itemId

Id of the work item to start the work timer

Response fields

Path Type Description

code

String

the result of the API operation

data.amountOfWork

Number

the amount of work already spent on this work timer

data.type

String

the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/startWorkTimer?token=00000000000&itemId=9846251' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/user/startWorkTimer?token=00000000000&itemId=9846251 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91

{
  "code" : "SUCCESS",
  "data" : {
    "type" : "SUCCESS",
    "amountOfWork" : 6.0
  }
}

Pause work timer

GET https://app.onedesk.com/rest/2.0/user/pauseWorkTimer

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.amountOfWork

Number

the amount of work already spent on this work timer

data.type

String

the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/pauseWorkTimer?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/user/pauseWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91

{
  "code" : "SUCCESS",
  "data" : {
    "type" : "SUCCESS",
    "amountOfWork" : 6.0
  }
}

Resume work timer

GET https://app.onedesk.com/rest/2.0/user/resumeWorkTimer

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.amountOfWork

Number

the amount of work already spent on this work timer

data.type

String

the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/resumeWorkTimer?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/user/resumeWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91

{
  "code" : "SUCCESS",
  "data" : {
    "type" : "SUCCESS",
    "amountOfWork" : 6.0
  }
}

Reset work timer

GET https://app.onedesk.com/rest/2.0/user/resetWorkTimer

Request parameters

Parameter Description

token

authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.amountOfWork

Number

the amount of work already spent on this work timer

data.type

String

the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/user/resetWorkTimer?token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/user/resetWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91

{
  "code" : "SUCCESS",
  "data" : {
    "type" : "SUCCESS",
    "amountOfWork" : 6.0
  }
}

User/Customer Team API

Get user teams

POST https://app.onedesk.com/rest/2.0/userteam/get

Request fields

Path Type Description

authenticationToken

String

Authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data

Array

list of organization user/customer teams (see response example for details)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/userteam/get' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000"
}'

Example request

POST /rest/2.0/userteam/get HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 43

{
  "authenticationToken" : "00000000000"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 134

{
  "code" : "SUCCESS",
  "data" : [ {
    "id" : 1,
    "name" : "team1",
    "category" : "USER",
    "userIds" : [ 23, 25 ]
  } ]
}

Activity API

Get followed discussions

POST https://app.onedesk.com/rest/2.0/activity/getFollowedDiscussions

Request fields

Path Type Description

authenticationToken

String

Authentication token

offset

Number

offset of the pagination

limit

Number

limit of the pagination

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

Total number of followed activities

data.items.[].followedActivityId

Number

Id of the followed activity

data.items.[].timestamp

Date

Date and time of the activity

data.items.[].author.id

Number

Id of the author

data.items.[].author.name

String

name of the author

data.items.[].author.pictureKey

String

profile picture key of the author

data.items.[].author.color

String

profile picture color of the author

data.items.[].author.type

String

type of the author

data.items.[].author.isDeleted

Boolean

the author is deleted

data.items.[].itemId

Number

Id of the item

data.items.[].itemName

String

Name of the item

data.items.[].newValueName

String

new value name

data.items.[].newValue

String

new value

data.items.[].read

Boolean

is this followed activity read?

data.items.[].activityDetails

String

activity details

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/activity/getFollowedDiscussions' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "offset" : 0,
  "limit" : 10
}'

Example request

POST /rest/2.0/activity/getFollowedDiscussions HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 75

{
  "authenticationToken" : "00000000000",
  "offset" : 0,
  "limit" : 10
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1065

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ {
      "followedActivityId" : 65835,
      "timestamp" : "2019-10-18T11:09:08:347+00:00",
      "author" : {
        "id" : 851651,
        "name" : "John Smith",
        "pictureKey" : "k1",
        "type" : "USER_TYPE_1",
        "color" : "#FF0000",
        "isDeleted" : false
      },
      "itemId" : 51651,
      "itemName" : "Modify all the products",
      "newValueName" : "Are you sure?",
      "newValue" : "DiscussionPost.985143",
      "read" : true,
      "activityDetails" : "_author_jabber_id_"
    }, {
      "followedActivityId" : 8156,
      "timestamp" : "2019-10-18T11:09:08:347+00:00",
      "author" : {
        "id" : 123547,
        "name" : "Derek Gold",
        "pictureKey" : "k2",
        "type" : "USER_TYPE_2",
        "color" : "#FF0000",
        "isDeleted" : false
      },
      "itemId" : 858156,
      "itemName" : "Delete typos",
      "newValueName" : "Done!",
      "newValue" : "DiscussionPost.1581526",
      "read" : false,
      "activityDetails" : "_author_jabber_id_2_"
    } ],
    "total" : 2
  }
}

Mark followed discussion as read

GET https://app.onedesk.com/rest/2.0/activity/markAsRead

Request parameters

Parameter Description

token

authentication token

followedActivityId

Id of the followed item

Response fields

Path Type Description

code

String

the result of the API operation

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/activity/markAsRead?token=00000000000&followedActivityId=6541251' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/activity/markAsRead?token=00000000000&followedActivityId=6541251 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41

{
  "code" : "SUCCESS",
  "data" : null
}

History API

Get item updates

POST https://app.onedesk.com/rest/2.0/history/getItemUpdates

Request fields

Path Type Description

authenticationToken

String

authentication token

applicationId

String

unique application ID to track updated/changes

itemTypes

Array

array of item types to filter

itemIds

Array

array of item IDs to filter

operations

Array

array of operations to filter (CREATE, DELETE, PROPERTY_UPDATE, ADD_TO_COLLECTION, REMOVE_FROM_COLLECTION)

propertyNames

Array

array of property names to filter

newValues

Array

array of new values to filter

oldValues

Array

array of old values to filter

filters

Array

array of 2nd order filters

filters.[].propertyName

String

name of the property of the 2nd order filter ([custom field name], authorId, spaceName)

filters.[].operation

String

operation of the 2nd order filter (EQ, NE, NOT_EMPTY)

filters.[].value

String

the value of the property of 2nd order filter

filters.[].isCustomField

Boolean

set this to true for custom field/property 2nd order filter

Response fields

Path Type Description

code

String

the result of the API operation

data

Array

array of history items (see example of response)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/history/getItemUpdates' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "applicationId" : "app_1",
  "itemTypes" : [ ],
  "itemIds" : [ ],
  "operations" : [ ],
  "propertyNames" : [ ],
  "newValues" : [ ],
  "oldValues" : [ ],
  "filters" : [ {
    "propertyName" : "Custom Field 1",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  }, {
    "propertyName" : "spaceName",
    "operation" : "EQ",
    "value" : "Space 1",
    "isCustomField" : false
  } ]
}'

Example request

POST /rest/2.0/history/getItemUpdates HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 459

{
  "authenticationToken" : "00000000000",
  "applicationId" : "app_1",
  "itemTypes" : [ ],
  "itemIds" : [ ],
  "operations" : [ ],
  "propertyNames" : [ ],
  "newValues" : [ ],
  "oldValues" : [ ],
  "filters" : [ {
    "propertyName" : "Custom Field 1",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  }, {
    "propertyName" : "spaceName",
    "operation" : "EQ",
    "value" : "Space 1",
    "isCustomField" : false
  } ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 522

{
  "code" : "SUCCESS",
  "data" : [ {
    "collectedTimestamp" : "2019-10-18T11:09:08:433+00:00",
    "authorId" : 3,
    "itemType" : "ProjectTask",
    "itemId" : 1,
    "parentItemType" : null,
    "parentItemId" : null,
    "itemName" : "item1",
    "operation" : "PROPERTY_UPDATE",
    "propertyName" : "description",
    "newValue" : "nv1",
    "newValueName" : null,
    "oldValue" : "ov1",
    "oldValueName" : null,
    "organizationId" : 1,
    "spaceId" : 4,
    "loadedTimestamp" : "2019-10-18T11:09:08:434+00:00",
    "blackList" : null
  } ]
}

Work items API

Get todo list

POST https://app.onedesk.com/rest/2.0/workitem/getToDoItems

Request fields

Path Type Description

authenticationToken

String

Authentication token

offset

Number

Offset of the pagination

limit

Number

Limit of the pagination

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

total number of items

data.items.[].id

Number

Id of the work item

data.items.[].name

String

Name of the work item

data.items.[].type

String

Type of the work item

data.items.[].plannedFinish

Number

Planned finish of the work item

data.items.[].lifecycleStatusId

Number

Lifecycle status id of the work item

data.items.[].numberOfComments

Number

Number of comments in the work item

data.items.[].priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

data.items.[].createDate

Date

creation date of the work item

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/getToDoItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "filterId" : 123,
  "limit" : 10,
  "offset" : 0
}'

Example request

POST /rest/2.0/workitem/getToDoItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 95

{
  "authenticationToken" : "00000000000",
  "filterId" : 123,
  "limit" : 10,
  "offset" : 0
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 627

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ {
      "id" : 6948156,
      "name" : "Define the planning for next release",
      "type" : "TASK_TYPE_1",
      "plannedFinish" : "2019-10-18T11:09:09:011+00:00",
      "createDate" : "2019-10-18T11:09:09:011+00:00",
      "lifecycleStatusId" : 561581,
      "priority" : 20,
      "numberOfComments" : 2
    }, {
      "id" : 488456,
      "name" : "The blue button doesn't work",
      "type" : "TASK_TYPE_2",
      "plannedFinish" : "2019-10-18T11:09:09:011+00:00",
      "createDate" : "2019-10-18T11:09:09:011+00:00",
      "lifecycleStatusId" : 126447,
      "priority" : 100,
      "numberOfComments" : 18
    } ],
    "total" : 2
  }
}

Search items

POST https://app.onedesk.com/rest/2.0/workitem/searchItems

Request fields

Path Type Description

authenticationToken

String

authentication token

itemIds

Array

array of item IDs to filter

filters

Array

array of filters

filters.[].propertyName

String

name of the property to filter ([custom field name], authorId, spaceName, edited, requesterId)

filters.[].operation

String

operation of the filter (EQ, NE, NOT_EMPTY, LE, GE) where LE, GE applicable for dates, e.g. "edited" property

filters.[].value

String

the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS and all numerical values should be integers (12 not 12.00))

filters.[].isCustomField

Boolean

set this to true for custom field filter OR set this to false for other property filter

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

total number of IDs

data.items

Array

array of IDs of the items

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/searchItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "Custom Field 1",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  } ]
}'

Example request

POST /rest/2.0/workitem/searchItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 202

{
  "authenticationToken" : "00000000000",
  "itemIds" : [ ],
  "filters" : [ {
    "propertyName" : "Custom Field 1",
    "operation" : "NOT_EMPTY",
    "value" : "",
    "isCustomField" : true
  } ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ 1, 2 ],
    "total" : 2
  }
}

Update work item

POST https://app.onedesk.com/rest/2.0/workitem/updateWorkItem

Request fields

Path Type Description

authenticationToken

String

authentication token

itemId

Number

the id of the item

name

String

name of the item

description

String

description of the item

priority

Number

priority of the item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

progress

Number

progress of the item

relatedItemIds

Array

array of IDs of the linked items

customFields

Object

object (map) of properties/values of custom fields

lifecycleStatusName

String

lifecycle status name of the item

edited

String

lifecycle status name of the item

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

the id of the updated item

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/updateWorkItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "itemId" : 1,
  "name" : "new name",
  "description" : "updated description",
  "priority" : 40,
  "progress" : 90.0,
  "relatedItemIds" : [ 2, 3 ],
  "customFields" : {
    "customField1" : "value1"
  },
  "lifecycleStatusName" : "In Progress",
  "edited" : null
}'

Example request

POST /rest/2.0/workitem/updateWorkItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 310

{
  "authenticationToken" : "00000000000",
  "itemId" : 1,
  "name" : "new name",
  "description" : "updated description",
  "priority" : 40,
  "progress" : 90.0,
  "relatedItemIds" : [ 2, 3 ],
  "customFields" : {
    "customField1" : "value1"
  },
  "lifecycleStatusName" : "In Progress",
  "edited" : null
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 59

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 15474
  }
}

Create work item

POST https://app.onedesk.com/rest/2.0/workitem/createWorkItem

Request fields

Path Type Description

authenticationToken

String

authentication token

type

String

the type of the item

name

String

name of the item

description

String

description of the item

attachmentIds

Array

attachment ids

spaceId

Number

Id of the container (optional)

priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

requesterIds

Array

IDs of the requesters

customFields

Object

object (map) of properties/values of custom fields

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

the id of the created item

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/createWorkItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "name" : "new name",
  "description" : "my description",
  "attachmentIds" : [ "0d984f0a", "6c5d4a02", "6c5d4a03" ],
  "type" : "FEEDBACK_TYPE_1",
  "spaceId" : 321,
  "priority" : 0,
  "requesterIds" : [ 33 ],
  "customFields" : null
}'

Example request

POST /rest/2.0/workitem/createWorkItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 281

{
  "authenticationToken" : "00000000000",
  "name" : "new name",
  "description" : "my description",
  "attachmentIds" : [ "0d984f0a", "6c5d4a02", "6c5d4a03" ],
  "type" : "FEEDBACK_TYPE_1",
  "spaceId" : 321,
  "priority" : 0,
  "requesterIds" : [ 33 ],
  "customFields" : null
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 57

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 151
  }
}

Get work item details

GET https://app.onedesk.com/rest/2.0/workitem/getItemDetails

Request parameters

Parameter Description

token

authentication token

workItemId

Id of the work item

organizationalId

OR by organizationalId of the work item

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

work item id

data.organizationalId

Number

work item id in the organization

data.spaceId

Number

space id

data.name

String

name of the work item

data.description

String

description of the work item

data.type

String

type of the work item

data.plannedFinish

Date

planned finish of the work item

data.createDate

Date

creation date of the work item

data.companyName

String

company name of the work item

data.teamName

String

team name of the work item

data.projectName

String

project name of the work item

data.organizationName

String

organization name of the requester of the work item

data.requester

String

requester of the work item

data.requesterType

String

the type of the requester of the work item

data.workPerformed

Number

work performed of the work item

data.priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

data.numberOfComments

Number

number of comments in the work item

data.numberOfAttachments

Number

number of attachments in the work item

data.assigned

Boolean

Is the current user assigned to this work item?

data.lifecycleStatusId

Number

lifecycle id of the work item

data.agilePoints

Number

Number of agile points of the work item

data.scheduledDurationAmount

Number

planned duration amount of the work item

data.scheduledDurationUnit

String

planned duration unit of the work item (DAYS, HOURS)

data.percentComplete

Number

percent complete of the work item

data.requesterIds

Array

IDs of the requesters

data.customFields

Object

object (map) of properties/values of custom fields

data.attachments.[].fileId

Number

id of the attachment

data.attachments.[].identityKey

String

key of the attachment

data.attachments.[].name

String

name of the attachment

data.attachments.[].contentType

String

content type of the attachment

data.posts.[].id

Number

Id of the comment

data.posts.[].title

String

title of the comment

data.posts.[].content

String

body of the comment

data.posts.[].author.id

Number

author id of the comment

data.posts.[].author.type

String

author type of the comment

data.posts.[].author.name

String

author name of the comment

data.posts.[].author.pictureKey

String

profile picture key of the author of the comment

data.posts.[].author.color

String

profile picture color of the author of the comment

data.posts.[].creationDate

Date

creation date of the comment

data.posts.[].relatedItemId

Number

Id of the item related to this comment

data.posts.[].postType

String

Comment type (OLD_REQUESTER_ONLY_POST, PUBLIC_DISCUSSION_POST, PRIVATE_DISCUSSION_POST)

data.posts.[].replies

Array

Replies of this comment (with the same properties)

data.posts.[].attachments

Array

the attachments of the post

data.posts.[].author.isDeleted

Boolean

true if the author is deleted

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItemDetails?token=00000000000&workItemId=695165&organizationalId=102' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/workitem/getItemDetails?token=00000000000&workItemId=695165&organizationalId=102 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2163

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 695165,
    "organizationalId" : 102,
    "name" : "The blue button doesn't work",
    "requester" : "requester",
    "requesterType" : "requesterType",
    "companyName" : "company name",
    "teamName" : "team name",
    "organizationName" : "organization name",
    "projectName" : "project name",
    "description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
    "type" : "TASK_TYPE_2",
    "plannedFinish" : "2019-10-18T11:09:09:968+00:00",
    "createDate" : "2019-10-18T11:09:09:968+00:00",
    "workPerformed" : 1,
    "priority" : 80,
    "numberOfComments" : 2,
    "numberOfAttachments" : 1,
    "lifecycleStatusId" : 65165,
    "agilePoints" : 2,
    "scheduledDurationAmount" : 1.0,
    "scheduledDurationUnit" : "DAYS",
    "percentComplete" : 30.0,
    "attachments" : [ {
      "fileId" : 514954,
      "name" : "Blue bug.jpg",
      "identityKey" : "k1",
      "contentType" : "image/jpeg"
    } ],
    "posts" : [ {
      "id" : 513258,
      "title" : "I don't see this bug",
      "content" : "I have tried <strong>everything</strong>, but I cannot reproduce this issue",
      "author" : {
        "id" : 12354,
        "name" : "John Smith",
        "pictureKey" : "k1",
        "type" : "USER_TYPE_1",
        "color" : "#FF0000",
        "isDeleted" : false
      },
      "creationDate" : "2019-10-18T11:09:09:969+00:00",
      "relatedItemId" : 695165,
      "postType" : "PRIVATE_DISCUSSION_POST",
      "replies" : [ {
        "id" : 98258,
        "title" : "Ho ok now I see it",
        "content" : "Ho ok now I see it, <strong>this<strong> actually was easy",
        "author" : {
          "id" : 12354,
          "name" : "John Smith",
          "pictureKey" : "k2",
          "type" : "USER_TYPE_1",
          "color" : "#FF0000",
          "isDeleted" : false
        },
        "creationDate" : "2019-10-18T11:09:09:969+00:00",
        "relatedItemId" : 695165,
        "postType" : "PRIVATE_DISCUSSION_POST",
        "replies" : [ ],
        "attachments" : [ ]
      } ],
      "attachments" : [ ]
    } ],
    "spaceId" : 1,
    "customFields" : null,
    "requesterIds" : [ 33 ],
    "assigned" : true
  }
}

Get work item details 2

GET https://app.onedesk.com/rest/2.0/workitem/getItemDetails2

Request parameters

Parameter Description

token

authentication token

workItemId

Id of the work item

organizationalId

OR by organizationalId of the work item

Reponse fields

Path Type Description

code

String

the result of the API operation

data.id

Number

work item id

data.organizationalId

Number

work item id in the organization

data.name

String

name of the work item

data.description

String

description of the work item

data.type

Object

type of the work item

data.lifecycleStatus.id

Number

lifecycle status id of the work item

data.lifecycleStatus.name

String

lifecycle status name of the work item

data.priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

data.created

Date

creation date of the work item

data.edited

Date

edit date of the work item

data.latestInProgress

Number

last time the work item status was changed to 'in progress'

data.latestClose

Date

last close date of the work item

data.author.id

Number

author id

data.author.type

String

author type

data.author.displayName

String

author display name

data.author.email

String

author email

data.author.teamName

String

author team name

data.assignees.[].id

Number

assignee id

data.assignees.[].type

String

assignee type

data.assignees.[].displayName

String

assignee display name

data.assignees.[].email

String

assignee email

data.assignees.[].teamName

String

assignee team name

data.assignedTeams.[].id

Number

assigned team id

data.assignedTeams.[].name

String

assigned team name

data.timesheets

Array

IDs of the associated timesheets

data.project.id

Number

project id

data.project.name

String

project name

data.agilePoints

Number

agile points of the work item

data.linkedItems

Array

IDs of the linked items

data.published

Boolean

true if the item is published

data.actual.startDate

Date

actual start date of the work item

data.actual.finishDate

Date

actaul finish date of the work item

data.actual.cost

Number

actual cost of the work item

data.actual.work

Number

actual work of the work item

data.actual.workunit

String

work unit (actual)

data.actual.completion

Number

actual completion

data.planned.startDate

Date

planned start date of the work item

data.planned.finishDate

Date

finish date of the work item

data.planned.type

String

type of the work item

data.planned.work

Number

planned work of the work item

data.planned.workunit

String

work unit (planned)

data.planned.cost

Number

planned cost of the work item

data.attachments.[].id

String

id of the attachment

data.attachments.[].name

String

name of the attachment

data.attachments.[].contentType

String

content type of the attachment

data.customFields.[].name

String

custom field name

data.customFields.[].value

String

custom field value

data.customFields.[].isDefault

Boolean

true if it is the default value

data.followers.[].type

String

follower type

data.followers.[].requester

Boolean

true if the follower is a requester

data.followers.[].user.id

Number

follower id

data.followers.[].user.type

String

follower user type

data.followers.[].user.displayName

String

follower display name

data.followers.[].user.email

String

follower email

data.followers.[].user.teamName

String

follower team name

data.followers.[].team.id

Number

following team id

data.followers.[].team.name

String

following team name

data.sla

String

sla of the work item

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItemDetails2?token=00000000000&workItemId=695165&organizationalId=102' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/workitem/getItemDetails2?token=00000000000&workItemId=695165&organizationalId=102 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2096

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 695165,
    "organizationalId" : 102,
    "name" : "The blue button doesn't work",
    "description" : "Why is the blue button not working. It was working last week!",
    "type" : {
      "id" : "FEEDBACK_TYPE_1",
      "name" : "ticket"
    },
    "lifecycleStatus" : {
      "id" : 65165,
      "name" : "open"
    },
    "priority" : 80,
    "created" : "2019-10-18T11:09:09:073+00:00",
    "edited" : "2019-10-18T11:09:09:073+00:00",
    "latestInProgress" : "2019-10-18T11:09:09:073+00:00",
    "latestClose" : "2019-10-18T11:09:09:073+00:00",
    "author" : {
      "id" : 1,
      "type" : "CUSTOMER_TYPE_1",
      "displayName" : "Sample User",
      "email" : "user@onedesk.com",
      "teamName" : "Team"
    },
    "assignees" : [ {
      "id" : 1,
      "type" : "CUSTOMER_TYPE_1",
      "displayName" : "Sample User",
      "email" : "user@onedesk.com",
      "teamName" : "Team"
    } ],
    "assignedTeams" : [ {
      "id" : 1,
      "name" : "Team"
    } ],
    "timesheets" : [ 123 ],
    "project" : {
      "id" : 1,
      "name" : "Test Project"
    },
    "agilePoints" : 2,
    "linkedItems" : [ 123 ],
    "published" : true,
    "actual" : {
      "startDate" : "2019-10-18T11:09:09:073+00:00",
      "finishDate" : "2019-10-18T11:09:09:073+00:00",
      "cost" : 100.0,
      "work" : 1.0,
      "workunit" : "MAN_DAYS",
      "completion" : 1.0
    },
    "planned" : {
      "startDate" : "2019-10-18T11:09:09:073+00:00",
      "finishDate" : "2019-10-18T11:09:09:073+00:00",
      "type" : "WORK",
      "work" : 1.0,
      "workunit" : "MAN_DAYS",
      "cost" : 100.0
    },
    "attachments" : [ {
      "id" : "k1",
      "name" : "Blue bug.jpg",
      "contentType" : "image/jpeg"
    } ],
    "customFields" : [ {
      "name" : "points",
      "value" : "5",
      "isDefault" : true
    } ],
    "followers" : [ {
      "type" : "USER",
      "user" : {
        "id" : 1,
        "type" : "CUSTOMER_TYPE_1",
        "displayName" : "Sample User",
        "email" : "user@onedesk.com",
        "teamName" : "Team"
      },
      "team" : {
        "id" : 1,
        "name" : "Team"
      },
      "requester" : true
    } ],
    "sla" : "sample SLA"
  }
}

Get items by IDs

POST https://app.onedesk.com/rest/2.0/workitem/getItems

Request fields

Path Type Description

authenticationToken

String

Authentication token

workItemIds

Array

array of work item IDs

Response fields

Path Type Description

code

String

the result of the API operation

data.total

Number

total number of items

data.items

Array

work items (see /rest/2.0/workitem/getItemDetails service for details)

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "workItemIds" : [ 695165, 695166 ]
}'

Example request

POST /rest/2.0/workitem/getItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 81

{
  "authenticationToken" : "00000000000",
  "workItemIds" : [ 695165, 695166 ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2320

{
  "code" : "SUCCESS",
  "data" : {
    "items" : [ {
      "id" : 695165,
      "organizationalId" : 102,
      "name" : "The blue button doesn't work",
      "requester" : "requester",
      "requesterType" : "requesterType",
      "companyName" : "company name",
      "teamName" : "team name",
      "organizationName" : "organization name",
      "projectName" : "project name",
      "description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
      "type" : "TASK_TYPE_2",
      "plannedFinish" : "2019-10-18T11:09:08:994+00:00",
      "createDate" : "2019-10-18T11:09:08:994+00:00",
      "workPerformed" : 1,
      "priority" : 80,
      "numberOfComments" : 2,
      "numberOfAttachments" : 1,
      "lifecycleStatusId" : 65165,
      "agilePoints" : 2,
      "scheduledDurationAmount" : 1.0,
      "scheduledDurationUnit" : "DAYS",
      "percentComplete" : 30.0,
      "attachments" : [ {
        "fileId" : 514954,
        "name" : "Blue bug.jpg",
        "identityKey" : "k1",
        "contentType" : "image/jpeg"
      } ],
      "posts" : [ ],
      "spaceId" : 1,
      "customFields" : null,
      "requesterIds" : [ 33 ],
      "assigned" : true
    }, {
      "id" : 695166,
      "organizationalId" : 102,
      "name" : "The blue button doesn't work",
      "requester" : "requester",
      "requesterType" : "requesterType",
      "companyName" : "company name",
      "teamName" : "team name",
      "organizationName" : "organization name",
      "projectName" : "project name",
      "description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
      "type" : "TASK_TYPE_2",
      "plannedFinish" : "2019-10-18T11:09:08:994+00:00",
      "createDate" : "2019-10-18T11:09:08:994+00:00",
      "workPerformed" : 1,
      "priority" : 80,
      "numberOfComments" : 2,
      "numberOfAttachments" : 1,
      "lifecycleStatusId" : 65165,
      "agilePoints" : 2,
      "scheduledDurationAmount" : 1.0,
      "scheduledDurationUnit" : "DAYS",
      "percentComplete" : 30.0,
      "attachments" : [ {
        "fileId" : 514954,
        "name" : "Blue bug.jpg",
        "identityKey" : "k1",
        "contentType" : "image/jpeg"
      } ],
      "posts" : [ ],
      "spaceId" : 1,
      "customFields" : null,
      "requesterIds" : [ 33 ],
      "assigned" : true
    } ],
    "total" : 2
  }
}

Create comment

POST https://app.onedesk.com/rest/2.0/workitem/createComment

Request fields

Path Type Description

token

String

Authentication token

itemId

Number

Id of the work item to post a comment on

description

String

Comment content

postType

String

Comment type (OLD_REQUESTER_ONLY_POST, PUBLIC_DISCUSSION_POST, PRIVATE_DISCUSSION_POST)

parentPostId

Number

Id of the parent comment (null if new thread)

attachmentIds

Array

Attachment ids

Response fields

Path Type Description

code

String

the result of the API operation

data

Number

Id of the newly created comment

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/workitem/createComment' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "parentPostId" : null,
  "itemId" : 564654,
  "attachmentIds" : [ "uuid1", "uuid2", "uuid3" ],
  "token" : "00000000000",
  "description" : "This button should not be red, it should be blue",
  "postType" : "PRIVATE_DISCUSSION_POST"
}'

Example request

POST /rest/2.0/workitem/createComment HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 238

{
  "parentPostId" : null,
  "itemId" : 564654,
  "attachmentIds" : [ "uuid1", "uuid2", "uuid3" ],
  "token" : "00000000000",
  "description" : "This button should not be red, it should be blue",
  "postType" : "PRIVATE_DISCUSSION_POST"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 43

{
  "code" : "SUCCESS",
  "data" : 564362
}

Worklogs API

Create worklog

POST https://app.onedesk.com/rest/2.0/worklog/createWorklog

Request fields

Path Type Description

authenticationToken

String

Authentication token

itemId

Number

Id of the work item to create a worklog on

percentage

Number

percentage of the work done

comments

String

comment on the worklog

dateStart

Date

start date of the worklog

dateFinish

Date

finish date of the worklog

works

Number

number of hours of work performed for this worklog

lifecycleStatusId

Number

Id of the new lifecycle status for the work item

billable

Boolean

The worklog is billable

Response fields

Path Type Description

code

String

the result of the API operation

data

Number

Id of the newly created worklog

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/worklog/createWorklog' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "itemId" : 894365,
  "dateStart" : "2019-10-18T11:09:08:819+00:00",
  "dateFinish" : "2019-10-18T11:09:08:819+00:00",
  "works" : 5.0,
  "percentage" : 50.4,
  "billable" : false,
  "comments" : "Fix the button color",
  "lifecycleStatusId" : 591954
}'

Example request

POST /rest/2.0/worklog/createWorklog HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 260

{
  "authenticationToken" : "00000000000",
  "itemId" : 894365,
  "dateStart" : "2019-10-18T11:09:08:819+00:00",
  "dateFinish" : "2019-10-18T11:09:08:819+00:00",
  "works" : 5.0,
  "percentage" : 50.4,
  "billable" : false,
  "comments" : "Fix the button color",
  "lifecycleStatusId" : 591954
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 43

{
  "code" : "SUCCESS",
  "data" : 564362
}

Get worklog

POST https://app.onedesk.com/rest/2.0/worklog/getItem

Request fields

Path Type Description

authenticationToken

String

Authentication token

id

Number

id of the worklog to get

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

id of the worklog

data.percentage

Number

percentage of the work done

data.dateStart

Date

start date of the worklog

data.dateFinish

Date

finish date of the worklog

data.work

Number

number of hours of work performed for this worklog

data.cost

Number

cost of the worklog based on the amount of work performed

data.status

String

status of the worklog

data.workItemId

Number

id of the item of the worklog

data.workItemName

String

name of the item of the worklog

data.resourceUserId

Number

user id of the worklog resource

data.spaceId

Number

space id of the worklog

data.billable

Boolean

worklog is billable

data.comments

String

worklog comments

data.requesterIds

Array

IDs of the requesters

data.requesterEmails

Array

email of the requesters

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/worklog/getItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "authenticationToken" : "00000000000",
  "id" : 1
}'

Example request

POST /rest/2.0/worklog/getItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55

{
  "authenticationToken" : "00000000000",
  "id" : 1
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 521

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 1,
    "dateStart" : "2019-10-18T11:09:08:819+00:00",
    "dateFinish" : "2019-10-18T11:09:08:819+00:00",
    "work" : 5.0,
    "cost" : 5,
    "percentage" : 50.4,
    "status" : "NOT_APPROVED_YET",
    "workItemId" : 2,
    "workItemName" : "task name",
    "resourceUserId" : 3,
    "spaceId" : 45,
    "comments" : "This is a comment.",
    "billable" : false,
    "requesterIds" : [ 1, 2, 3 ],
    "requesterEmails" : [ "requester1@onedesk.com", "requester2@onedesk.com", "requester3@onedesk.com" ]
  }
}

Customer portal API

Get Organization Details

GET https://app.onedesk.com/rest/2.0/customerportal/organizationDetails

Request parameters

Parameter Description

uri

URI of the organization

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

Organization id

data.uri

String

organization URI

data.name

String

Organization name

data.canSubmitAnonymously

Boolean

Can user submit item anonymously

data.displayUserContainers

Boolean

Display only user/customer containers at customer portal

data.viewWorkItemsList

Boolean

Can user view the list of work items

data.viewMyWorkItems

Boolean

Can the user see his work items?

data.viewPreviouslySubmittedItems

Boolean

Can user view the list of previously submitted work items

data.lifecycleStatusVisibleForLoggedIn

Boolean

Can users see lifecycle status

data.lifecycleStatusVisibleForEveryBody

Boolean

Can anybody see lifecycle status

data.showFormBranding

Boolean

choose to show the branding on the creating form

data.showPortalBranding

Boolean

choose to show the branding on the customer portal

data.showCustomerApp

Boolean

choose to extend customer portal app

data.dateFormat

String

date format in organization setting

data.calendar

Object

organization calendar data

data.currencyCode

String

currency code in organization setting

data.spaces.[].id

Number

Container id

data.spaces.[].name

String

Container name

data.spaces.[].type.name

String

Container type name

data.spaces.[].type.label

String

Container type label

data.spaces.[].type.iconClassName

String

Container type icon style

data.spaces.[].type.iconColor

Number

Container type icon color

data.fileUrl

String

Url to load files

data.generatedCss

String

generated file css id

data.langKey

String

default language

data.customLangFileId

String

custom language file id

data.logo

String

logo file id

data.forms

Array

creation forms

data.statuses

Object

statuses for creation forms

data.customFieldDefinitions

Object

custom field definitions for creation forms

data.customerPortals

Object

customer portals

data.appearanceOptions

Object

customer portals appearance options

data.messenger

Object

messenger

data.webForms

Object

web forms

data.registrationPolicy

String

customer portals registration policy

data.itemTypes.[].name

String

item type name

data.itemTypes.[].label

String

item type label

data.itemTypes.[].iconClassName

String

item type icon style

data.itemTypes.[].iconColor

Number

item type icon color

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/organizationDetails?uri=acme' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/customerportal/organizationDetails?uri=acme HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2563

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 6513554,
    "uri" : "acme",
    "name" : "ACME Organization",
    "canSubmitAnonymously" : false,
    "viewWorkItemsList" : true,
    "viewMyWorkItems" : true,
    "lifecycleStatusVisibleForLoggedIn" : true,
    "lifecycleStatusVisibleForEveryBody" : false,
    "displayUserContainers" : false,
    "viewPreviouslySubmittedItems" : false,
    "spaces" : [ {
      "id" : 56465,
      "name" : "My project 1",
      "type" : {
        "name" : "SPACE_TYPE_0",
        "label" : "Project",
        "iconClassName" : "project_icon_style",
        "iconColor" : 56513
      }
    }, {
      "id" : 2365847,
      "name" : "My project 2",
      "type" : {
        "name" : "SPACE_TYPE_0",
        "label" : "Project",
        "iconClassName" : "project_icon_style",
        "iconColor" : 56513
      }
    } ],
    "itemTypes" : [ {
      "name" : "TASK_TYPE_1",
      "label" : "Task",
      "iconClassName" : "task_icon_style",
      "iconColor" : 651365
    }, {
      "name" : "TASK_TYPE_2",
      "label" : "Issue",
      "iconClassName" : "issue_icon_style",
      "iconColor" : 12354
    } ],
    "fileUrl" : "https://app.onedesk.com/cware/file/view",
    "generatedCss" : "key",
    "langKey" : "en",
    "customLangFileId" : "key",
    "logo" : "key",
    "forms" : [ ],
    "statuses" : { },
    "customFieldDefinitions" : { },
    "showPortalBranding" : true,
    "showFormBranding" : true,
    "showCustomerApp" : true,
    "dateFormat" : "yy/dd/MM",
    "customerPortals" : {
      "0" : {
        "id" : null,
        "activated" : null,
        "name" : null,
        "position" : null,
        "permissions" : null,
        "configurableFormIds" : [ ]
      }
    },
    "appearanceOptions" : {
      "id" : null,
      "mainColor" : null,
      "bodyColor" : null,
      "mainBGColor" : null,
      "menuBGColor" : null,
      "mainTextColor" : null,
      "secondaryButtonTextColor" : null,
      "secondaryButtonColor" : null,
      "langKey" : null,
      "customLangFileId" : null,
      "showBranding" : null,
      "showCustomerApp" : null,
      "logoType" : null,
      "logoUrl" : null
    },
    "messenger" : {
      "id" : null,
      "activated" : null,
      "name" : null,
      "position" : null
    },
    "webForms" : {
      "id" : null,
      "activated" : null,
      "name" : null,
      "position" : null
    },
    "calendar" : {
      "holidays" : null,
      "workingHoursPerDay" : null
    },
    "currencyCode" : "USD",
    "registrationPolicy" : "ALLOW_SELF_REGISTER"
  }
}

Get Work items list

GET https://app.onedesk.com/rest/2.0/customerportal/workItems

Request parameters

Parameter Description

uri

URI of the organization

cpId

customer portal ID

offset

offset of the pagination

limit

limit of the pagination

sort

sort (TRENDING, RECENT, POPULAR)

myWorkItems

filter to get only the user requester work items

followedItems

filter to get only the user followed work items

search

filter work items with a text search

type

filter work items by type

project

work items by project

token

Authentication token

Response fields

Path Type Description

code

String

the result of the API operation

data.totalResults

Number

totla number of result

data.typesToFilter

Array

types to filter

data.projectsToFilter

Array

projects to filter

data.statusesToFilter

Object

statuses to filter

data.workItems.[]id

Number

item id

data.workItems.[]organizationalId

Number

work item id in the organization

data.workItems.[]name

String

work item name

data.workItems.[]priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

data.workItems.[]projectId

Number

project id

data.workItems.[]projectName

String

project name

data.workItems.[]description

String

description of the work item

data.workItems.[]creationDate

Date

creation date of the work item

data.workItems.[]followersCount

Number

number of followers of the work item

data.workItems.[]followed

Boolean

true if the current user is following this work item

data.workItems.[]userSpecificFollower

Boolean

true if the current user is following this work item (only with a user tag, not part of a team are all XXXXX)

data.workItems.[]numberOfDiscussions

Number

number of discussions in the work item

data.workItems.[]numberOfAttachments

Number

number of attachments in the work item

data.workItems.[]constraintType

String

constraint type of the work item

data.workItems.[]constraintDate

Date

constraint date of the work item

data.workItems.[]plannedCost

Number

planned cost of the work item

data.workItems.[]plannedWork

Number

planned work of the work item

data.workItems.[]plannedWorkUnit

String

planned work unit of the work item

data.workItems.[]customFields

Object

custom fields of the work item

data.workItems.[]status.id

Number

Id of the lifecycle status of the work item

data.workItems.[]status.label

String

label of the lifecycle status of the work item

data.workItems.[]status.default

Boolean

status of the work item is default

data.workItems.[]status.iconColor

Number

icon color of the lifecycle status of the work item

data.workItems.[]isRequester

Boolean

true if the current user is the requester of the work item

data.workItems.[]percentComplete

Number

percent complete of the work item

data.workItems.[]actualWork

Number

actual work of the work item

data.workItems.[]actualStart

Date

actual start date of the work item

data.workItems.[]actualFinish

Date

actual finish date of the work item

data.workItems.[]actualCostAmount

Number

actual cost amount of the work item

data.workItems.[]edited

Date

edited date of the work item

data.workItems.[]latestClose

Number

latest close of the work item

data.workItems.[]latestInProgress

Number

latest in progress of the work item

data.workItems.[]author

String

author of the work item

data.workItems.[]assignmentsName

Array

assignments names of the work item

data.workItems.[]requestersName

Array

requesters names of the work item

data.workItems.[]sla

String

name of sla applied to the work item

data.workItems.[]nextSLABreach

String

next sla breach of the work item

data.workItems.[]type.name

String

item type name

data.workItems.[]type.label

String

item type label

data.workItems.[]type.iconClassName

String

item type icon style

data.workItems.[]type.iconColor

Number

item type icon color

data.workItems.[]attachments.[].fileId

Number

id of the attachment

data.workItems.[]attachments.[].identityKey

String

key of the attachment

data.workItems.[]attachments.[].name

String

name of the attachment

data.workItems.[]attachments.[].contentType

String

content type of the attachment

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/workItems?uri=acme&cpId=1&offset=0&limit=10&sort=TRENDING&myWorkItems=false&followedItems=false&search=bug&type=TASK_TYPE_1&project=958416&token=00000000000' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/customerportal/workItems?uri=acme&cpId=1&offset=0&limit=10&sort=TRENDING&myWorkItems=false&followedItems=false&search=bug&type=TASK_TYPE_1&project=958416&token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 3333

{
  "code" : "SUCCESS",
  "data" : {
    "workItems" : [ {
      "id" : 56142,
      "organizationalId" : 128,
      "name" : "Is this the right color for the button?",
      "priority" : 60,
      "type" : {
        "name" : "TASK_TYPE_1",
        "label" : "Task",
        "iconClassName" : "task_icon_style",
        "iconColor" : 15654
      },
      "description" : "The button on the right is red, shouldn't it be blue?",
      "creationDate" : "2019-10-18T11:09:08:461+00:00",
      "numberOfDiscussions" : 2,
      "numberOfAttachments" : 1,
      "status" : {
        "id" : 5641,
        "label" : "Open",
        "iconColor" : 54651,
        "default" : false
      },
      "attachments" : [ {
        "fileId" : 514954,
        "name" : "Blue bug.jpg",
        "identityKey" : "k1",
        "contentType" : "image/jpeg"
      } ],
      "isRequester" : true,
      "followersCount" : 1,
      "constraintType" : "ASAP",
      "constraintDate" : "2019-10-18T11:09:08:462+00:00",
      "plannedCost" : 1.0,
      "plannedWork" : 2.0,
      "plannedWorkUnit" : "MAN_DAYS",
      "customFields" : { },
      "projectId" : 1,
      "projectName" : "Sample Project",
      "percentComplete" : 33.0,
      "actualWork" : 1.0,
      "actualStart" : "2019-10-18T11:09:08:462+00:00",
      "actualFinish" : "2019-10-18T11:09:08:462+00:00",
      "actualCostAmount" : 0.0,
      "edited" : "2019-10-18T11:09:08:462+00:00",
      "latestClose" : "2019-10-18T11:09:08:462+00:00",
      "latestInProgress" : "2019-10-18T11:09:08:462+00:00",
      "author" : "user 1",
      "assignmentsName" : [ ],
      "requestersName" : [ ],
      "sla" : "Test SLA",
      "nextSLABreach" : "Closed",
      "followed" : true,
      "userSpecificFollower" : true
    }, {
      "id" : 5814926,
      "organizationalId" : 128,
      "name" : "There is a bug in the menu",
      "priority" : 80,
      "type" : {
        "name" : "TASK_TYPE_1",
        "label" : "Task",
        "iconClassName" : "task_icon_style",
        "iconColor" : 15654
      },
      "description" : "There is a bug in the menu, when I click on it, it doesn't open",
      "creationDate" : "2019-10-18T11:09:08:462+00:00",
      "numberOfDiscussions" : 2,
      "numberOfAttachments" : 1,
      "status" : {
        "id" : 5641,
        "label" : "Open",
        "iconColor" : 54651,
        "default" : false
      },
      "attachments" : [ {
        "fileId" : 514954,
        "name" : "Blue bug.jpg",
        "identityKey" : "k1",
        "contentType" : "image/jpeg"
      } ],
      "isRequester" : false,
      "followersCount" : 5,
      "constraintType" : "ASAP",
      "constraintDate" : "2019-10-18T11:09:08:462+00:00",
      "plannedCost" : 1.0,
      "plannedWork" : 2.0,
      "plannedWorkUnit" : "MAN_DAYS",
      "customFields" : { },
      "projectId" : 1,
      "projectName" : "Sample Project",
      "percentComplete" : 50.0,
      "actualWork" : 1.0,
      "actualStart" : "2019-10-18T11:09:08:462+00:00",
      "actualFinish" : "2019-10-18T11:09:08:462+00:00",
      "actualCostAmount" : 0.0,
      "edited" : "2019-10-18T11:09:08:462+00:00",
      "latestClose" : "2019-10-18T11:09:08:462+00:00",
      "latestInProgress" : "2019-10-18T11:09:08:462+00:00",
      "author" : "user 1",
      "assignmentsName" : [ ],
      "requestersName" : [ ],
      "sla" : "Test SLA 2",
      "nextSLABreach" : "1 day 2:30 late",
      "followed" : false,
      "userSpecificFollower" : false
    } ],
    "totalResults" : 2,
    "typesToFilter" : [ ],
    "projectsToFilter" : [ ],
    "statusesToFilter" : { }
  }
}

Get Work item

GET https://app.onedesk.com/rest/2.0/customerportal/workItems/{workItemId}

Path parameters

Table 1. /rest/2.0/customerportal/workItems/{workItemId}
Parameter Description

workItemId

Id of the work item

Request parameters

Parameter Description

token

Authentication token

cpId

customer portal ID

Response fields

Path Type Description

code

String

the result of the API operation

data.id

Number

item id

data.organizationalId

Number

work item id in the organization

data.name

String

work item name

data.priority

Number

priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively)

data.projectId

Number

project id

data.projectName

String

project name

data.description

String

description of the work item

data.creationDate

Date

creation date of the work item

data.followersCount

Number

number of followers of the work item

data.followed

Boolean

true if the current user is following this work item

data.userSpecificFollower

Boolean

true if the current user is following this work item (only with a user tag, not part of a team are all XXXXX)

data.numberOfDiscussions

Number

number of discussions in the work item

data.numberOfAttachments

Number

number of attachments in the work item

data.constraintType

String

constraint type of the work item

data.constraintDate

Date

constraint date of the work item

data.plannedCost

Number

planned cost of the work item

data.plannedWork

Number

planned work of the work item

data.plannedWorkUnit

String

planned work unit of the work item

data.customFields

Object

custom fields of the work item

data.status.id

Number

Id of the lifecycle status of the work item

data.status.label

String

label of the lifecycle status of the work item

data.status.default

Boolean

status of the work item is default

data.status.iconColor

Number

icon color of the lifecycle status of the work item

data.isRequester

Boolean

true if the current user is the requester of the work item

data.percentComplete

Number

percent complete of the work item

data.actualWork

Number

actual work of the work item

data.actualStart

Date

actual start date of the work item

data.actualFinish

Date

actual finish date of the work item

data.actualCostAmount

Number

actual cost amount of the work item

data.edited

Date

edited date of the work item

data.latestClose

Number

latest close of the work item

data.latestInProgress

Number

latest in progress of the work item

data.author

String

author of the work item

data.assignmentsName

Array

assignments names of the work item

data.requestersName

Array

requesters names of the work item

data.sla

String

name of sla applied to the work item

data.nextSLABreach

String

next sla breach of the work item

data.type.name

String

item type name

data.type.label

String

item type label

data.type.iconClassName

String

item type icon style

data.type.iconColor

Number

item type icon color

data.attachments.[].fileId

Number

id of the attachment

data.attachments.[].identityKey

String

key of the attachment

data.attachments.[].name

String

name of the attachment

data.attachments.[].contentType

String

content type of the attachment

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/workItems/56142?token=00000000000&cpId=1' -i -H 'Accept: application/json'

Example request

GET /rest/2.0/customerportal/workItems/56142?token=00000000000&cpId=1 HTTP/1.1
Accept: application/json
Host: app.onedesk.com

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1504

{
  "code" : "SUCCESS",
  "data" : {
    "id" : 56142,
    "organizationalId" : 128,
    "name" : "Is this the right color for the button?",
    "priority" : 60,
    "type" : {
      "name" : "TASK_TYPE_1",
      "label" : "Task",
      "iconClassName" : "task_icon_style",
      "iconColor" : 15654
    },
    "description" : "The button on the right is red, shouldn't it be blue?",
    "creationDate" : "2019-10-18T11:09:08:868+00:00",
    "numberOfDiscussions" : 2,
    "numberOfAttachments" : 1,
    "status" : {
      "id" : 5641,
      "label" : "Open",
      "iconColor" : 54651,
      "default" : false
    },
    "attachments" : [ {
      "fileId" : 514954,
      "name" : "Blue bug.jpg",
      "identityKey" : "k1",
      "contentType" : "image/jpeg"
    } ],
    "isRequester" : true,
    "followersCount" : 1,
    "constraintType" : "ASAP",
    "constraintDate" : "2019-10-18T11:09:08:868+00:00",
    "plannedCost" : 1.0,
    "plannedWork" : 2.0,
    "plannedWorkUnit" : "MAN_DAYS",
    "customFields" : { },
    "projectId" : 1,
    "projectName" : "Sample Project",
    "percentComplete" : 33.0,
    "actualWork" : 1.0,
    "actualStart" : "2019-10-18T11:09:08:868+00:00",
    "actualFinish" : "2019-10-18T11:09:08:868+00:00",
    "actualCostAmount" : 0.0,
    "edited" : "2019-10-18T11:09:08:868+00:00",
    "latestClose" : "2019-10-18T11:09:08:868+00:00",
    "latestInProgress" : "2019-10-18T11:09:08:868+00:00",
    "author" : "user 1",
    "assignmentsName" : [ ],
    "requestersName" : [ ],
    "sla" : "Test SLA",
    "nextSLABreach" : "Closed",
    "followed" : true,
    "userSpecificFollower" : true
  }
}

Login

POST https://app.onedesk.com/rest/2.0/customerportal/login
You should either send the email, the password and the uri OR the cookie

Request fields

Path Type Description

email

String

Email of the user

password

String

password of the user

uri

String

Uri of the organization

rememberMe

Boolean

Remember the login by generating a cookie in the response

cookie

String

Login cookie

token

String

login token

Response fields

Path Type Description

code

String

the result of the API operation

data.name

String

user name

data.uri

String

Uri of the organization

data.authenticationToken

String

Authentication token

data.cookie

String

Cookie to be used next time the user want to login

data.userId

Number

User ID

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "uri" : "acme",
  "cookie" : "",
  "token" : "",
  "email" : "john.smith@acme.com",
  "password" : "XXXXXXXXX",
  "rememberMe" : true
}'

Example request

POST /rest/2.0/customerportal/login HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 139

{
  "uri" : "acme",
  "cookie" : "",
  "token" : "",
  "email" : "john.smith@acme.com",
  "password" : "XXXXXXXXX",
  "rememberMe" : true
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 204

{
  "code" : "SUCCESS",
  "data" : {
    "name" : "John Smith",
    "uri" : "acme",
    "authenticationToken" : "00000000000",
    "cookie" : "4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
    "userId" : 1
  }
}

Logout

POST https://app.onedesk.com/rest/2.0/customerportal/logout

Request fields

Path Type Description

token

String

Authentication token

Response fields

Path Type Description

code

String

the result of the API operation

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/logout' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "token" : "00000000000"
}'

Example request

POST /rest/2.0/customerportal/logout HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 29

{
  "token" : "00000000000"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41

{
  "code" : "SUCCESS",
  "data" : null
}

Registration

POST https://app.onedesk.com/rest/2.0/customerportal/register

Request fields

Path Type Description

email

String

user email address

uri

String

Organization uri

Response fields

Path Type Description

code

String

the result of the API operation

data.redirectionUrl

String

the url to redirect to in order ton confirm the registration

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/register' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "uri" : "acme",
  "email" : "john.smith@acme.com"
}'

Example request

POST /rest/2.0/customerportal/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55

{
  "uri" : "acme",
  "email" : "john.smith@acme.com"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 182

{
  "code" : "SUCCESS",
  "data" : {
    "redirectionUrl" : "http://onedesk.com/html/confirmation?uuid=4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
    "userId" : 1,
    "error" : ""
  }
}

Reset password

POST https://app.onedesk.com/rest/2.0/customerportal/resetPasswordRequest

Request fields

Path Type Description

email

String

user email address

uri

String

Organization uri

Response fields

Path Type Description

code

String

the result of the API operation

Example curl request

$ curl 'https://app.onedesk.com/rest/2.0/customerportal/resetPasswordRequest' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "uri" : "acme",
  "email" : "john.smith@acme.com"
}'

Example request

POST /rest/2.0/customerportal/resetPasswordRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55

{
  "uri" : "acme",
  "email" : "john.smith@acme.com"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41

{
  "code" : "SUCCESS",
  "data" : null
}

Error Handling

HTTP response status

Here are the supported HTTP response status

HTTP response status Description

200

Success

500

Internal server error

401

Authentication error

403

Security error

Response codes

Every request to the API will return a response code. Here is a list of all possible code and their description.

code Description

SUCCESS

The request successfully executed

ERROR_PORTAL_DISABLED

Customer portal is disabled in the organization, you cannot use the customer portal API

ERROR_CANNOT_FIND_ITEM

Cannot find the specified item

ERROR_CANNOT_FIND_USER

cannot find the user

ERROR_CANNOT_FIND_ORGANIZATION

cannot find the organization

ERROR_LOGIN_FAILED

login failed

ERROR_COOKIE_LOGIN_FAILED

login with cookie failed

ERROR_AUTHENTICATION_FROM_TOKEN_FAILED

authentication with token failed

ERROR_AUTHENTICATION_REQUIRED

authentication required to execute the request

ERROR_SECURITY_ACCESS

security access error

ERROR_ITEM_NOT_PUBLISHED

Item not publish, so request cannot be executed

ERROR_INVALID_PAGINATION

invalid pagination

ERROR_PAGINATION_NOT_SUPPORTED

pagination not supported

ERROR_INVALID_EMAIL

invalid email

ERROR_INVALID_FILTER

invalid filter

ERROR_INVALID_FILTERID

invalid filter id

ERROR_REGISTRATION_NOT_ALLOWED

registration not allowed (contact the administrator of your organization)

ERROR_REGISTRATION_CUSTOMER_ALREADY_EXIST

customer with the same email already exist

ERROR_SUBMIT_NAME_IS_REQUIRED

name of the work item required

ERROR_SUBMIT_DESCRIPTION_IS_REQUIRED

description of the work item required

ERROR_SUBMIT_TYPE_IS_REQUIRED

type of the work item required

ERROR_SUBMIT_TYPE_IS_WRONG

Wrong type, this type is not allowed on the customer portal

ERROR_SUBMIT_WRONG_PRIORITY

wrong priority (must be between 0 and 100)

ERROR_SUBMIT_PROJECT_NOT_FOUND

Container not found

ERROR_SUBMIT_PROJECT_NOT_PUBLISHED

Container not published on the customer portal

ERROR_SUBMIT_ANONYMOUS_MUST_PROVIDE_EMAIL

email is required when submitting an anonymous work item

ERROR_USER_ALREADY_EXIST

user email already exist

ERROR_CANNOT_FIND_PARENT_POST

cannot find the parent post

UNKNOWN_ERROR

unknown error, please contact OneDesk with the details of you request

INTERNAL_ERROR

internal error, please contact OneDesk with the details of you request

ERROR_CANNOT_FIND_CUSTOMER

cannot find this customer